Chapter 3. Widget Class Members and Methods

#include "act_grf.h"
#include "pv_factory.h"

class myWidget : public activeGraphicClass {

   .
   .
   .

  int x - x coordinate of object origin ( 0,0 is upper left )

  int y - y coordinate of object origin ( 0,0 is upper left )

  int w - object width

  int h - object height

  char *name - object name

  char *createParam - extra information a widget might receive when created;
                      used so one widget may be a control or readback

                      (see Chapter ? - Packaging Widgets)

  int sboxX, sboxY, sboxW, sboxH - selection box region definition; widget
                                   code simply keeps these in sync with
                                   x, y, w, h


  Widget dc - drag context (not needed by most widgets)

  int dragIndex - index used in drag and drop functions;
                  use illustrated in the example widget code

  int objType - 1=graphics, 2=monitors, 3=controls, -1=unknown
                used in conjuction with createParam

  int enabled - if 0 then widget should be unmapped/invisible and nonfunctional

  activeWindowClass *actWin - used to hold a copy of the active
                              window object pointer; set only in the methods
                              createInteractive and createFromFile

  void *aglPtr - will hold the activeGraphicListPtr container pointer;
                 use illustrated in the example widget code; widget code
                 must set this in method activate; used to queue deferred
                 processing request

---------------------------------------------------------------------------

Default Constructor - if the widget class name is myWidgetClass then this
                      is declared as

  myWidgetClass::myWidgetClass ( void );

  This method initializes all applicable object members.

  All widgets at least set name equal to the class name. For example

    name = strdup( "myWidgetClass" );

---------------------------------------------------------------------------

Copy Constructor - if the widget class name is myWidgetClass then this
                   is declared as

  myWidgetClass::myWidgetClass (
   const myWidgetClass *source );

  This method first calls the base class clone method.

  It then makes a copy of edit mode attributes of *source and
  initializes all execute mode attributes.

---------------------------------------------------------------------------

Destructor - if the widget class name is myWidgetClass then this
             is declared as

  myWidgetClass::~myWidgetClass ( void );

  This function frees all dynamically allocated memory. At least it does
  the following:

    if ( name ) delete name;

    updateBlink( 0 );

---------------------------------------------------------------------------

char *objName ( void );

  Return object component name (See section on packaging widgets).

---------------------------------------------------------------------------

int createInteractive (
  activeWindowClass *aw_obj,
  int _x,
  int _y,
  int _w,
  int _h );

  Create the widget in response to interactive user request. All
  widgets do the following:

  actWin = (activeWindowClass *) aw_obj;
  x = _x;
  y = _y;
  w = _w;
  h = _h;

---------------------------------------------------------------------------

int createFromFile (
  FILE *f,
  char *name,
  activeWindowClass *_actWin );

  Create the widget in response to file open request. All
  widgets do the following:

    this->actWin = _actWin;

  All widgets should use the tagClass object to read in object
  attributes labeled with tags.

---------------------------------------------------------------------------

int save (
  FILE *f )

  Serialize object.

  All widgets should use the tagClass object to write object
  attributes labeled with tags.

---------------------------------------------------------------------------

void edit ( void );

  Edit object attributes.

---------------------------------------------------------------------------

int erase ( void );

  Erase the edit mode widget image.

---------------------------------------------------------------------------

int draw ( void );

  Draw the edit mode widget image.

---------------------------------------------------------------------------

void updateDimensions ( void );

  Update the position information for any internal image details
  if necessary.

---------------------------------------------------------------------------

char *firstDragName ( void );

  Return the first name in the set of all names associated with
  drag and drop operations.

---------------------------------------------------------------------------

char *nextDragName ( void );

  Return the next name in the set of all names associated with
  drag and drop operations. If there are no more, return NULL.

---------------------------------------------------------------------------

char *dragValue (
  int i );

  Return the value of the ith item associated with drag and drop operations.

  If the items are expStringClass objects, then if actWin->mode == AWC_EXECUTE
  the return the expanded value else return the raw value.

---------------------------------------------------------------------------

void changeDisplayParams (
  unsigned int _flag,
  char *_fontTag,
  int _alignment,
  char *_ctlFontTag,
  int _ctlAlignment,
  char *_btnFontTag,
  int _btnAlignment,
  int _textFgColor,
  int _fg1Color,
  int _fg2Color,
  int _offsetColor,
  int _bgColor,
  int _topShadowColor,
  int _botShadowColor );

  Depending on the value of _flag, copy parameter values into the
  associated class members of the widget.

  _flag bit values are shown below:

  #define ACTGRF_FONTTAG_MASK            1
  #define ACTGRF_ALIGNMENT_MASK          2
  #define ACTGRF_CTLFONTTAG_MASK         4
  #define ACTGRF_CTLALIGNMENT_MASK       8
  #define ACTGRF_TEXTFGCOLOR_MASK        0x10
  #define ACTGRF_FG1COLOR_MASK           0x20
  #define ACTGRF_FG2COLOR_MASK           0x40
  #define ACTGRF_OFFSETCOLOR_MASK        0x80
  #define ACTGRF_BGCOLOR_MASK            0x100
  #define ACTGRF_TOPSHADOWCOLOR_MASK     0x200
  #define ACTGRF_BOTSHADOWCOLOR_MASK     0x400
  #define ACTGRF_BTNFONTTAG_MASK         0x800
  #define ACTGRF_BTNALIGNMENT_MASK       0x1000

---------------------------------------------------------------------------

void changePvNames (
  int flag,
  int numCtlPvs,
  char *ctlPvs[],
  int numReadbackPvs,
  char *readbackPvs[],
  int numNullPvs,
  char *nullPvs[],
  int numVisPvs,
  char *visPvs[],
  int numAlarmPvs,
  char *alarmPvs[] );

  Depending on the value of _flag, copy parameter values into the
  associated class members of the widget.

  _flag bit values are shown below:

  #define ACTGRF_CTLPVS_MASK            1
  #define ACTGRF_READBACKPVS_MASK       2
  #define ACTGRF_NULLPVS_MASK           4
  #define ACTGRF_VISPVS_MASK            8
  #define ACTGRF_ALARMPVS_MASK          0x10

---------------------------------------------------------------------------

int activate (
  int pass,
  void *ptr );

  Activate widget in seven passes, i.e. this method is called seven times
  with pass ranging from 1 to 7.

  All widgets perform the following initialization:

      aglPtr = ptr;
      initEnable();

  All widgets should return 1 for every pass. Returning an even status
  value causes the display engine to call activate again in a retry
  mode without incrementing pass. This continues for some maximum number
  of retries. Between passes the engine dispatches process variable events
  and X Window events.

  Widgets should make a connect request to all process variables and perhaps
  add connection and value change event callbacks in this method.

---------------------------------------------------------------------------

int deactivate (
  int pass );

  This method is called in two passes, i.e. this method is called twice
  with pass ranging from 1 to 2.

  Widgets must clean up all execute mode related things including clearing
  process variable events and releasing the process variables.

---------------------------------------------------------------------------

int reactivate (
  int pass,
  void *ptr );

  This is similar to activate and does not need to be implemented. If
  not, the base class will call activate. This method is called after
  preReactivate. Process variable connection requests must be performed once
  again and callbacks added (if they were added in the execute method).
  This is called when a multiplexor widget changes a symbol in execute mode.

---------------------------------------------------------------------------

int preReactivate (
  int pass );

  This is similar to deactivate and does not need to be implemented. If
  not, the base class will call deactivate. This method can count on
  reactivate being called. Process variable events must be cleared and
  the process variables released, but other execute mode things can
  be left untouched. This is called when a multiplexor widget changes
  a symbol in execute mode.

---------------------------------------------------------------------------

int getButtonActionRequest (
  int *up,
  int *down,
  int *drag,
  int *focus );

  This method is used so the widget may inform the display engine about
  its interest in various mouse events. Setting a parameter to 1 means
  the widget wants the corresponding event; setting it to 0 means the
  widget does not.

---------------------------------------------------------------------------

void executeDeferred ( void );

  This method is called periodically by the display engine. The widget
  should check various class member flags and perform X I/O to update
  the execute mode images as appropriate.

  Other deferred event related activities may be performed here as well.

---------------------------------------------------------------------------

int expand1st (
  int numMacros,
  char *macros[],
  char *expansions[] );

  For each expStringClass object (named expStr below), the widget calls

    expStr.expand1st( numMacros, macros, expansions );

---------------------------------------------------------------------------

int expand2nd (
  int numMacros,
  char *macros[],
  char *expansions[] );

  For each expStringClass object (named expStr below), the widget calls

    expStr.expand2nd( numMacros, macros, expansions );

---------------------------------------------------------------------------

int containsMacros ( void );

  For each expStringClass object (named expStr below), the widget calls

    stat = expStr.containsPrimaryMacros();

    if any object returns 1, this method returns 1; else it returns 0.

---------------------------------------------------------------------------

void bufInvalidate ( void );

  The display engine calls this method and others in the following
  sequence:

    bufInvalidate();
    eraseActive();
    drawActive();

  The purpose of this method will be illustrated by the following
  senario. Suppose a widget draws an image, part of which is constant
  and part that changes with the value of a pv. Under normal conditions,
  only the part that changes with the value of the pv ever need be
  updated. Under certain conditions, however, everything needs to
  be redrawn, e.g. when a screen is iconified and then deiconified.

  If this method is implemented, a member named bufInvalid should
  exists and be initialized to 1 (image is invalid).

  The eraseActive method, if bufInvalid == 1, should erase everything.
  Otherwise it should only erase the part that changes with the value
  of the pv.

  The drawActive method, if bufInvalid == 1, should draw everything and
  then set bufInvalid to 0. Otherwise it should only draw the part that
  changes with the value of the pv.

  All widgets do not implement this method.

---------------------------------------------------------------------------

int eraseActive ( void );

  Erase the execute mode widget image.

---------------------------------------------------------------------------

int drawActive ( void );

  Draw the execute mode widget image.

---------------------------------------------------------------------------

void map ( void );

  This method need be implemented only by widgets that use
  motif (or some other X Toolkit). If so, the motif widgets
  must be mapped.

---------------------------------------------------------------------------

void unmap ( void );

  This method need be implemented only by widgets that use
  motif (or some other X Toolkit). If so, the motif widgets
  must be unmapped.

---------------------------------------------------------------------------

void btnUp (
  XButtonEvent *be,
  int x,
  int y,
  int buttonState,
  int buttonNumber,
  int *action );

  For control widgets. Widget takes appropriate "mouse button up"
  action. The parameter *action should normally be set to 0. Setting
  it to 1 will cause the screen to close.

---------------------------------------------------------------------------

void btnDown (
  XButtonEvent *be,
  int x,
  int y,
  int buttonState,
  int buttonNumber,
  int *action );

  For control widgets. Widget takes appropriate "mouse button down"
  action. The parameter *action should normally be set to 0. Setting
  it to 1 will cause the screen to close.

---------------------------------------------------------------------------

void btnDrag (
  XMotionEvent *me,
  int x,
  int y,
  int buttonState,
  int buttonNumber );

  For control widgets. Widget takes appropriate "mouse button drag"
  action.

---------------------------------------------------------------------------

void pointerIn (
  int _x,
  int _y,
  int buttonState );

  Mouse pointer has crossed into region occupied by widget. Widget
  may take some action. If several widgets overlap, this method is
  called only for the topmost one.

---------------------------------------------------------------------------

void pointerOut (
  XMotionEvent *me,
  int x,
  int y,
  int buttonState );

  Mouse pointer has exited the region occupied by widget. Widget
  may take some action. If several widgets overlap, this method is
  called only for the topmost one.

---------------------------------------------------------------------------

void mousePointerIn (
  XMotionEvent *me,
  int _x,
  int _y,
  int buttonState );

  Most widgets do not implement this method.

  Mouse pointer has crossed into region occupied by widget. Widget
  may take some action. If several widgets overlap, this method is
  called for each one.

---------------------------------------------------------------------------

void mousePointerOut (
  XMotionEvent *me,
  int _x,
  int _y,
  int buttonState );

  Most widgets do not implement this method.

  Mouse pointer has exited the region occupied by widget. Widget
  may take some action. If several widgets overlap, this method is
  called for each one.