WidgetHandler Tutorial - EdgarReynaldo/EagleGUI GitHub Wiki

Intro

The WidgetHandler class in Eagle handles all the mundane task of getting graphics, input, and updates from the widgets it holds. Normally when you want to run a WidgetHandler you will call WidgetBase class functions that have been overridden by the WidgetHandler. WidgetHandler handles widgets z-order, redraw flags and dirty rectangles in the GUI. It handles dispatching display, events, and updates to all the widgets it holds. A WidgetHandler also has a root layout that controls the positions of all the widgets in the handler. You can change the focus with Tab or any key that you set. WidgetHandler uses forwarded layout functions to add and remove widgets from the root layout. They are passed to the root layout for positioning.

For base class functions of the WidgetHandler, see WidgetBase.hpp and the Widget Tutorial.

To create a WidgetHandler object use the constructor (WidgetHandler). Pass in the graphics context you wish the handler to draw on and an optional value for class and name.

Since all widgets start with an area of 0x0, you need to give your WidgetHandler an area to occupy on the screen. This is done with the WidgetBase function SetWidgetArea. Pass it an WIDGETAREA or a Rectangle and pass false to notify_layout since it is top level and has no layout.

If you passed NULL for the constructor's graphics context, you may now set it and setup the background and drawing buffer for it. See the SetupBuffer function for details. Pass a width, height, and graphics context to draw on.

Adding Widgets

That sums up the basic setup functions for your WidgetHandler. We will now move on to adding widgets and getting our GUI ready. Every WidgetHandler comes with a DumbLayout as the default layout. Since this is usually not what we want we should specify what kind of layout to use with SetRootLayout. After you have set the root layout, you will want to add your widgets to the WidgetHandler. Adding widgets to a widget handler adds them automatically to the root layout. The following functions are for adding and removing widgets from your WidgetHandler.

   /// Functions for adding widgets to the handler - automatically added to the layout
   
   void AddWidget(WidgetBase* widget);///< Adds a widget at the end of the widget list
   WidgetHandler& operator<<(WidgetBase* widget);///< Stream operator adds the widget pointed to to the gui
   WidgetHandler& operator<<(WidgetBase& widget);///< Stream operator adds the widget reference to the gui

   /// Functions to remove widgets and clear the layout
   
   void RemoveWidget(WidgetBase* widget);///< Remove a widget from this gui
   void ClearLayout();///< Removes all widgets from the dialog. Global WH's should probably call this.

You may add a widget to your handler by using AddWidget or by using the stream in operator. The stream operator will work on either a widget reference or pointer. RemoveWidget removes a specific widget specified by the widget parameter, and ClearLayout will remove all widgets from the handler and its layout.

Changing the focus

You can change which widget has the focus by using the following functions :

   /// The focus cycling functions will only function if this is the top level widget handler
   void CycleFocusForward();///< Like pressing the tab key
   void CycleFocusBackward();///< Like pressing shift tab

These two functions will shift the focus by one index either forward or backward. Default shortcut keys to these functions are TAB and SHFT-TAB.

You may set the focus directly by using the following function :

   bool GiveWidgetFocus(WidgetBase* widget , bool notify_parent = true);///< Give widget the focus. notify_parent is for internal use only

Pass the specified widget and it will be given the focus. This makes it last in the drawing list and first in the input list.

Drawing helper functions

   void PerformFullRedraw(EagleGraphicsContext* win);///< Perform a full redraw, ignoring and clearing redraw flags
   void PerformPartialRedraw(EagleGraphicsContext* win);///< Perform a partial redraw of the widgets and bg areas that are dirty

   void DrawBuffer(EagleGraphicsContext* win);///< Draws the buffer
   void DrawToWindow(EagleGraphicsContext* win , int xpos , int ypos);///< Draws the buffer to the window drawing target

   virtual void SetBackgroundColor(const EagleColor color);///< Set the background color

   void AlwaysClear(bool always) {always_clear = always;SetRedrawFlag();}
   
   void SetFullRedraw();///< Call to fully redraw everything

Normally you don't need to call PerformFullRedraw or PerformPartialRedraw because the widget handler handles redraw by itself, using dirty rectangles. DrawBuffer and DrawToWindow are only helper functions. Drawing is normally managed by calling Display. You may set the background color of the widget handler's buffer by calling SetBackgroundColor. If you are an advanced user and you don't want to use dirty rectangles you may pass true to the AlwaysClear function. SetFullRedraw will set full redraw for one drawing cycle only.