Using Widget Superclasses

This chapter covers the following topics:

PtWidget
PtBasic
PtContainer
PtCompound
PtGenList
PtGenTree
PtLabel
PtGraphic
PtGauge

This chapter describes the common widget superclasses. Use this information to determine whether a superclass's method does what you need for your widget. With this knowledge you can decide whether to take over the method (override inheritance), add a method to the chain, or use the PtSuperClass* functions.

It's important to read the specifications of each of your widget's superclasses before using any of the PtSuperClass*() functions.

`PtWidget`

The PtWidget superclass provides the fundamental functionality of all Photon widgets.

Class hierarchy

PtWidget

Class flags

Pt_RECTANGULAR

Methods

PtWidget defines the class methods described below.

Defaults method

None.

Initialization method

None.

Extent method

Calculates the extent of the widget without accounting for borders or margins. The extent is calculated based on the widget's position (Pt_ARG_POS) and dimension (Pt_ARG_DIM). For disjoint widgets (e.g. PtWindow widgets), the position is assumed to be (0, 0).

Connection method

Determines if the widget needs a region, and if so, what events the region should be opaque and/or sensitive to.

If the widget has a bitmap cursor defined, it's set up as region data. If the widget already has a region, that region is updated with the opaque/sense and region data. This is done through PhRegionChange().

If the widget doesn't have a region but one is required, it's created through PhRegionOpen().

Finally, if the widget isn't a window, any hotkey callbacks attached to the widget are registered with the nearest disjoint parent (of PtWindow class). This is done through PtSetResources().

Realization method

None.

Unrealization method

If the widget has a region, the region is closed. All descendants (widget->rid members) are set to 0. If the widget isn't a window, any attached hotkey callbacks are detached from its disjoint parent.

The extent of this widget is damaged on the parent. All children of this widget are unrealized. Any of these widgets having a constraining parent with Pt_SET_CHILD_UNREALIZED_F defined has that function invoked. Any of these having a Pt_CB_UNREALIZED callback chain has that callback chain invoked (from the top down).

Destruction method

Called when a widget instance is being removed. Frees widget->widget_data. Any memory automatically allocated by a resource is released (this memory shouldn't be freed in the Destruction method). Any resources you free must have the pointer set to NULL to prevent the widget engine from freeing the memory a second time. The following resource types automatically allocate and release memory:

Pt_ARG_IS_ALLOC
Pt_ARG_IS_ARRAY
Pt_ARG_IS_CALLBACK_LIST
Pt_ARG_IS_LINK
Pt_ARG_IS_STRING

Widget actions

Raw callbacks are supported for Ph_EV_BUT_PRESS, Ph_EV_BUT_RELEASE, Ph_EV_BUT_REPEAT, and Ph_EV_KEY events.

If there are callbacks in the Pt_CB_FILTER callback chain having an event mask that matches the current event type, those callbacks are invoked. If the value returned by a filter callback is greater than 0, that value is returned. If there are balloons registered with this widget, the balloon list is checked to determine if a balloon needs to be inflated and/or deflated.

If the event is a Ph_EV_KEY event, the event is given to the focused child of the widget, if there is one. If the event isn't consumed by the widget, the hotkey chain of the nearest disjoint parent is processed to see if the key is a hotkey. If a matching hotkey definition is found, the hotkey callback is invoked and the event is consumed (by returning Pt_END).

If the event is a button press, release, or repeat, each child widget intersecting the event is found via PtContainerHit() until one of these widgets consumes the event.

When an intersecting widget is found, the event rectangle is translated relative to the upper-left corner of the intersecting widget's canvas. Once translation has been performed, the event is given to the intersecting widget via absorbed = PtEventHandler(). Upon return, the event rectangle is detranslated by the same amount.

If all the following are true:

the event was a button press
the event hasn't yet directed focus
the current intersecting widget has the Pt_GETS_FOCUS flag set

then focus is given to that widget and event->processing_flags has its Ph_DIRECTED_FOCUS bit set. If the return from PtEventHandler() was Pt_END, the event is considered consumed and Pt_END is returned.

An extra step is performed if the event is a press and _Pt_->current is NULL: the absorbing widget is recorded for the purposes of delivering phantom releases to the appropriate widget at a later time.

if( widget->rid ) 
    //if the event was not absorbed, take it back.
    cbinfo->event->collector.rid = widget->rid;

if( ( ( absorbed != Pt_CONTINUE ) || 
      ( cbinfo->event->processing_flags & Ph_BACK_EVENT ) )
      &&  wp && cbinfo->event->type == Ph_EV_BUT_PRESS
      && ( !_Pt_->current || _Pt_->current == wp ) )
    {
    if ( wp->flags & Pt_DESTROYED )
        _Pt_->current = (PtWidget_t *)Pt_END;
    else
        _Pt_->current = wp;
    }

Once the event has been consumed or there are no more intersecting events, Pt_END is returned. Otherwise, absorbed is returned.

Resource definitions

static const PtResourceRec_t resources[] = {
    { Pt_ARG_AREA,          Pt_CHANGE_CANVAS, 0,
        Pt_ARG_IS_STRUCT( PtWidget_t, area )},
    { Pt_ARG_BEVEL_WIDTH,   Pt_CHANGE_CANVAS_REDRAW, 0,
        Pt_ARG_IS_NUMBER( PtWidget_t, border_width ) },
    { Pt_ARG_CURSOR_TYPE,       core_modify_cursor, 0,
        Pt_ARG_IS_NUMBER( PtWidget_t, cursor_type )},
    { Pt_ARG_CURSOR_COLOR,  core_modify_cursor, 0,
        Pt_ARG_IS_NUMBER( PtWidget_t, cursor_color )},
    { Pt_ARG_DATA,          Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_ALLOC( PtWidget_t, data )},
    { Pt_ARG_DIM,               Pt_CHANGE_CANVAS, 0,
        Pt_ARG_IS_STRUCT( PtWidget_t, area.size )},
    { Pt_ARG_FLAGS,         PtModifyFlags, 0,
        Pt_ARG_IS_FLAGS( PtWidget_t, flags )},
    { Pt_ARG_POS,               Pt_CHANGE_CANVAS, 0,
        Pt_ARG_IS_STRUCT( PtWidget_t, area.pos ) },
    { Pt_ARG_RESIZE_FLAGS,      Pt_CHANGE_RESIZE, 0,
        Pt_ARG_IS_FLAGS( PtWidget_t, resize_flags )},
    { Pt_CB_DESTROYED,      Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, destroyed )},
    { Pt_CB_HOTKEY,         core_modify_hotkey_callbacks, 0,
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, hotkeys )},
    { Pt_CB_RAW_EVENT,      core_modify_raw_callbacks, 0,
        Pt_ARG_IS_LINK( PtWidget_t, callbacks )},
    { Pt_CB_REALIZED,           Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, realized )},
    { Pt_CB_UNREALIZED,     Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, unrealized )},
    { Pt_ARG_USER_DATA,     Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_ALLOC( PtWidget_t, user_data )},
    { Pt_ARG_HELP_TOPIC,        Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_STRING( PtWidget_t, help_topic )
    },
    { Pt_CB_BLOCKED,            Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, blocked )},
    { Pt_ARG_BITMAP_CURSOR, bitmap_cursor_change, 0, 
        Pt_ARG_IS_ALLOC( PtWidget_t, bitmap_cursor )
    },
    { Pt_ARG_EFLAGS,    PtModifyEFlags, 0,
        Pt_ARG_IS_FLAGS( PtWidget_t, eflags )},
    { Pt_CB_IS_DESTROYED, Pt_CHANGE_INVISIBLE, 0, 
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, is_destroyed ) },
    { Pt_CB_DND, Pt_CHANGE_INVISIBLE, 0, 
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, dnd ) },
    { Pt_ARG_EXTENT,    core_modify_extent, 0,
        Pt_ARG_IS_STRUCT( PtWidget_t, extent ) },
    { Pt_CB_OUTBOUND, Pt_CHANGE_INVISIBLE, 0, 
        Pt_ARG_IS_CALLBACK_LIST( PtWidget_t, outbound ) },
    { Pt_ARG_WIDTH,             Pt_CHANGE_CANVAS, 0,
        Pt_ARG_IS_NUMBER( PtWidget_t, area.size.w )},
    { Pt_ARG_HEIGHT,                Pt_CHANGE_CANVAS, 0,
        Pt_ARG_IS_NUMBER( PtWidget_t, area.size.h )},
    { Pt_ARG_MINIMUM_DIM,           Pt_CHANGE_RESIZE, 0,
        Pt_ARG_IS_STRUCT( PtWidget_t, min_dim )},
    { Pt_CB_FILTER, Pt_CHANGE_INVISIBLE, NULL, 
        Pt_ARG_IS_LINK( PtWidget_t, filter ) },
    { Pt_ARG_POINTER, Pt_CHANGE_INVISIBLE, NULL, 
        Pt_ARG_IS_POINTER( PtWidget_t, ptr ) },
};

Functions

static core_modify_cursor()

Sets the resource via direct assignment and if realized, sets the Ph_REGION_CURSOR bit in widget->flags. If this flag is on when the PtUpdate() function is called (see the Photon Library Reference), a PhRegionChange() will be performed to change the region's cursor or create a region if one doesn't exist.

static core_modify_raw_callbacks()

Sets the resource via PtSetStruct() and adjusts the widget's region sensitivity.

static core_modify_hotkey_callbacks()

Sets the resource via PtSetStruct() and if realized, attaches any hotkey callbacks of a nonwindow widget to its disjoint parent.

int PtModifyFlags()

Knocks down the read-only flag bits from the mask and applies the remaining flag to widget->flags. A change in the following flag bits may cause the widget to change:

Pt_AUTOHIGHLIGHT: Requires a region and sensitivity to Ph_EV_BOUNDARY events via PhRegionChange() or the Connection method of PtWidget.
Pt_ETCH_HIGHLIGHT: Resize by setting the Pt_WIDGET_RESIZE bit in widget->flags.
Pt_SET: If Pt_SELECT_NOREDRAW isn't set in the widget flags, the widget will force a redraw by calling PtDamageWidget().
Pt_HIGHLIGHTED: The widget will force a redraw by calling PtDamageWidget().

`PtBasic`

Provides fundamental Photon widget behavior and callbacks.

Class hierarchy

PtWidget --> PtBasic

Class extensions

The PtBasic widget adds three class-level methods to fundamental widget functionality. For complete descriptions, see "Class methods" in the Anatomy of a Widget chapter.

typedef struct Pt_basic_widget_class {
     PtWidgetClass_t   core;
     void  (*got_focus_f)( PtWidget_t *, PhEvent_t * );
     void  (*lost_focus_f)( PtWidget_t *, PhEvent_t * );
     void  (*calc_opaque_f)( PtWidget_t * );
     } PtBasicWidgetClass_t;

#define Pt_SET_GOT_FOCUS_F (Pt_ARG_IS_POINTER(PtBasicWidgetClass_t,got_focus_f))
#define Pt_SET_LOST_FOCUS_F (Pt_ARG_IS_POINTER(PtBasicWidgetClass_t,lost_focus_f))
#define Pt_SET_CALC_OPAQUE_F (Pt_ARG_IS_POINTER(PtBasicWidgetClass_t,calc_opaque_f))

Methods

PtBasic defines the class methods described below.

Defaults method

 
widget->border_width = 1;
widget->cursor_color = Ph_CURSOR_DEFAULT_COLOR;
widget->resize_flags |= Pt_RESIZE_XY_AS_REQUIRED;
widget->eflags = Pt_DAMAGE_ON_FOCUS;

basic->border_color = basic->fill_color = Pg_LGREY;
basic->flags = Pt_ALL_ETCHES | Pt_ALL_BEVELS | 
                  Pt_ALL_OUTLINES | Pt_FLAT_FILL;
basic->inline_color = basic->outline_color = PgGrey( 0x4b );

Initialization method

None.

Extent method

Invokes the Extent method of PtWidget via PtSuperClassExtent(). The resulting extent is then adjusted to account for borders and margins.

The Extent method calculates the widget's opaque rectangle and determines whether the widget's Pt_OPAQUE flag is set. The opaque rectangle, widget->opaque, indicates:

the rectangle under which damage needn't occur if this widget is damaged
what should be damaged if this widget changes position or dimension

This rectangle is the area capable of obscuring any widgets beneath. Widgets completely obscured by another widget aren't drawn.

Connection method

Checks the PtBasic class structure member calc_opaque_f. If not NULL, the function is invoked. The calc_opaque_f() function is responsible for setting or clearing a widget's Pt_OPAQUE flag. If the widget has a rectangular area blocking anything beneath, the Pt_OPAQUE flag should be set and widget->opaque_rect should identify that rectangular area. Otherwise, the Pt_OPAQUE flag should be cleared.

If a widget's fill color is Pg_TRANSPARENT or has a basic->roundness that's greater than 0, the widget shouldn't be flagged as opaque.

Realization method

Inherited from PtWidget.

Draw method

PtBasic's Draw method draws a rectangle filled with the current fill color. The widget's border is rendered if the Pt_HIGHLIGHTED bit of the widget flags is set and the border width is greater than 0.

If the Pt_SET bit is set, the border is rendered inverted (i.e. the top border color is used to draw the bottom border and vice versa). PtBasic's Draw method also handles focus rendering.

Unrealization method

None.

Destruction method

None.

Got Focus method

Damages widgets having both the Pt_FOCUS_RENDER and Pt_DAMAGE_ON_FOCUS flags set. Highlights and invokes the basic->arm (Pt_CB_ARM) callback list if this widget has the Pt_AUTOHIGHLIGHT flag set. Invokes the basic->got_focus (Pt_CB_GOT_FOCUS) callback list using PtInvokeCallbackList().

Lost Focus method

Damages widgets having both the Pt_FOCUS_RENDER and Pt_DAMAGE_ON_FOCUS flags set. Unhighlights and invokes the basic->disarm (Pt_CB_DISARM) callback list if this widget has the Pt_AUTOHIGHLIGHT flag set. Invokes the basic->got_focus (Pt_CB_LOST_FOCUS) callback list via PtInvokeCallbackList().

Calc Opaque Rect method

Sets or clears the widget's Pt_OPAQUE flag (Pt_ARG_FLAGS resource) based on the widget's fill color, roundness, and current value of the Pt_RECTANGULAR flag in the widget class structure.

Widget actions

PtBasic is sensitive to the following events:

Ph_EV_BUT_PRESS: The widget sets/clears Pt_SET flags, invokes Pt_CB_ARM (and possibly Pt_CB_ACTIVATE if a toggle button is selected) and Pt_CB_MENU (if the right mouse button is pressed).
Ph_EV_BUT_REPEAT: The widget invokes the Pt_CB_REPEAT callbacks.
Ph_EV_BUT_RELEASE: The widget invokes the Pt_CB_DISARM callbacks. If a real release (as opposed to a phantom release) is received, the widget also invokes Pt_CB_ACTIVATE.
Ph_EV_BOUNDARY: The widget manages highlighting of widgets with the Pt_AUTOHIGHLIGHT flag set.

The raw callbacks return Pt_CONTINUE to allow chaining to continue.

If your widget class defines Pt_SET_RAW_CALLBACKS, keep this in mind: if your raw callback is sensitive to one of the events listed above and the callback returns Pt_END or Pt_HALT, PtBasic behavior for that event won't occur unless you invoke PtBasic's raw handlers within the callback prior to returning. This can be done via PtSuperClassRawEvent().

Resource definitions

static const PtResourceRec_t resources[] =
{
    { Pt_ARG_FLAGS, basic_modify_flags, NULL,
      Pt_ARG_IS_FLAGS( PtWidget_t, flags ) },
    { Pt_ARG_INLINE_COLOR, Pt_CHANGE_INVISIBLE, NULL,
      Pt_ARG_IS_COLOR( PtBasicWidget_t, inline_color ) },
    { Pt_ARG_COLOR, Pt_CHANGE_REDRAW, NULL,
      Pt_ARG_IS_COLOR( PtBasicWidget_t, color ) },
    { Pt_ARG_FILL_COLOR, Pt_CHANGE_INVISIBLE, NULL,
      Pt_ARG_IS_COLOR( PtBasicWidget_t, fill_color ) },
    { Pt_ARG_FILL_PATTERN, Pt_CHANGE_REDRAW, NULL,
      Pt_ARG_IS_STRUCT( PtBasicWidget_t, fill_pattern ) },
    { Pt_ARG_MARGIN_HEIGHT, Pt_CHANGE_CANVAS, NULL,
      Pt_ARG_IS_NUMBER( PtBasicWidget_t, margin_height ) },
    { Pt_ARG_MARGIN_WIDTH, Pt_CHANGE_CANVAS, NULL,
      Pt_ARG_IS_NUMBER( PtBasicWidget_t, margin_width ) },
    { Pt_ARG_OUTLINE_COLOR, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_COLOR( PtBasicWidget_t, outline_color ) },
    { Pt_CB_ARM, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_CALLBACK_LIST( PtBasicWidget_t, arm ) },
    { Pt_CB_DISARM, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_CALLBACK_LIST( PtBasicWidget_t, disarm ) },
    { Pt_CB_ACTIVATE, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_CALLBACK_LIST( PtBasicWidget_t, activate ) },
    { Pt_CB_GOT_FOCUS, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_CALLBACK_LIST( PtBasicWidget_t, got_focus ) },
    { Pt_CB_LOST_FOCUS, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_CALLBACK_LIST( PtBasicWidget_t, lost_focus ) },
    { Pt_CB_REPEAT, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_CALLBACK_LIST( PtBasicWidget_t, repeat ) },
    { Pt_ARG_TRANS_PATTERN, Pt_CHANGE_RESIZE_REDRAW, NULL, 
      Pt_ARG_IS_STRUCT( PtBasicWidget_t, trans_pattern ) },
    { Pt_ARG_BASIC_FLAGS, basic_modify_flags, NULL, 
      Pt_ARG_IS_FLAGS( PtBasicWidget_t, flags ) },
    { Pt_CB_MENU, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_CALLBACK_LIST( PtBasicWidget_t, menu ) },
    { Pt_ARG_CONTRAST, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_NUMBER( PtBasicWidget_t, contrast ) },
    { Pt_ARG_BEVEL_CONTRAST, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_NUMBER( PtBasicWidget_t, border_contrast ) },
    { Pt_ARG_BEVEL_COLOR, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_COLOR( PtBasicWidget_t, border_color ) },
    { Pt_ARG_LIGHT_FILL_COLOR, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_COLOR( PtBasicWidget_t, top_flat_color ) },
    { Pt_ARG_DARK_FILL_COLOR, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_COLOR( PtBasicWidget_t, bot_flat_color ) },
    { Pt_ARG_DARK_BEVEL_COLOR, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_COLOR( PtBasicWidget_t, bot_border_color ) },
    { Pt_ARG_LIGHT_BEVEL_COLOR, Pt_CHANGE_INVISIBLE, NULL, 
      Pt_ARG_IS_COLOR( PtBasicWidget_t, top_border_color ) },
};

Functions

static void basic_modify_flags()

For Pt_ARG_FLAGS, this function:

recalculates the opaque rectangle if a highlighting flag is changing
damages the widget if the Pt_GHOST flag is changing
lets any other flag changes be handled via PtSuperClassSetResources()

void basic_modify()

Sets the fill color and roundness values. Invokes the Connection method of PtBasic (which invokes the Calc Opaque Rect method), and reexamines the widget's clear/opaque status via PtUpdateVisibility().

Setting the Pt_CONSUME_EVENTS bit of PtWidget's eflags resource controls whether a widget consumes any event it's given. Container widgets set this bit by default to prevent events from passing through to the subclassed widgets beneath them.

`PtContainer`

This superclass provides a new origin, clipping, and constraints for widget children. If you're creating a widget with children, we recommend you make your widget a subclass of PtContainer or one of its subclasses.

A container can have its own Draw method to render any widget-specific data (other than children).

Class hierarchy

PtWidget --> PtBasic --> PtContainer

Class extensions

typedef struct Pt_container_widget_class {
    PtBasicWidgetClass_t    basic;
    void    (*child_created_f)( PtWidget_t *widget,
                                PtWidget_t *child );
    int     (*child_settingresource_f)(PtWidget_t *widget,
                                       PtWidget_t *child,
                                       PtArg_t const *argt);
    int     (*child_gettingresource_f)(PtWidget_t *widget,
                                       PtWidget_t *child,
                                       PtArg_t *argt );
    int     (*child_realizing_f)( PtWidget_t *widget,
                                  PtWidget_t *child );
    void    (*child_realized_f)( PtWidget_t *widget,
                                 PtWidget_t *child );
    void    (*child_unrealizing_f)( PtWidget_t *widget,
                                    PtWidget_t *child );
    void    (*child_unrealized_f)( PtWidget_t *widget,
                                   PtWidget_t *child );
    void    (*child_destroyed_f)( PtWidget_t *widget,
                                  PtWidget_t *child );
    void    (*child_move_resize_f)( PtWidget_t *widget,
                                    PtWidget_t *child,
                                    PhArea_t *current_area,
                                    PhRect_t *current_extent,
                                    PhArea_t *old_area,
                                    PhRect_t *old_extent );
    int     (*child_getting_focus_f)( PtWidget_t *widget,
                                      PtWidget_t *child,
                                      PhEvent_t *event );
    int     (*child_losing_focus_f)( PtWidget_t *widget,
                                     PtWidget_t *child,
                                     PhEvent_t *event );
    PtWidget_t * (*child_redirect_f)( PtWidget_t *,
                                      PtWidgetClassRef_t *);

} PtContainerClass_t;

#define Pt_SET_CHILD_SETTINGRESOURCE_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_settingresource_f))
#define Pt_SET_CHILD_GETTINGRESOURCE_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_gettingresource_f))
#define Pt_SET_CHILD_REALIZING_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_realizing_f))
#define Pt_SET_CHILD_REALIZED_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_realized_f))
#define Pt_SET_CHILD_UNREALIZING_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_unrealizing_f)) 
#define Pt_SET_CHILD_UNREALIZED_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_unrealized_f)) 
#define Pt_SET_CHILD_CREATED_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_created_f)) 
#define Pt_SET_CHILD_DESTROYED_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_destroyed_f)) 
#define Pt_SET_CHILD_MOVED_RESIZED_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_move_resize_f)) 
#define Pt_SET_CHILD_GETTING_FOCUS_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_getting_focus_f)) 
#define Pt_SET_CHILD_LOSING_FOCUS_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_losing_focus_f)) 
#define Pt_SET_CHILD_REDIRECT_F \
        (Pt_ARG_MODE_PTR|offsetof(PtContainerClass_t, \
                                  child_redirect_f))

Methods

PtContainer defines the class methods described below.

Defaults method

PtContainerWidget_t *ctnr =(PtContainerWidget_t *)widget;
PtBasicWidget_t *basic = (void *)widget;

widget->eflags |= Pt_CONSUME_EVENTS;
widget->border_width = 0;
widget->resize_flags &= ~Pt_RESIZE_XY_BITS;
basic->flags = Pt_ALL_BEVELS | Pt_FLAT_FILL;
ctnr->flags = Pt_ANCHOR_CHILD_HORIZONTAL |
                 Pt_ANCHOR_CHILD_VERTICAL |
                 Pt_CANVAS_INVALID | Pt_ENABLE_CUA |
                 Pt_ENABLE_CUA_ARROWS;

ctnr->title_font = strdup("TextFont09");

PtSetParentWidget( widget );

Initialization method

Registers with its parent for anchoring services.

Extent method

Finds the bounding box of widget children and applies its resize policy. The extent is calculated, and if the canvas is different as a result, all registered child containers are anchored. If the extent or canvas is different, the resize callback list of the widget is invoked. See PtSuperClassExtent() for a sample Extent method of a container.

Connection method

None.

Realization method

None.

Draw method

Inherited from PtBasic.

Unrealization method

Deregisters a widget from its parent. Destroys the current_balloon and sets it to NULL (if not NULL already).

Destruction method

Deregisters a widget from its parent.

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

Calc Opaque Rect method

Inherited from PtBasic.

Child Created method

None.

Child Realized/Unrealized method

static void container_child_realized_unrealized( 
    PtWidget_t *widget, PtWidget_t *child )
{
    PtContainerWidget_t *ctnr = 
       (PtContainerWidget_t *)widget;
    if( child->flags & Pt_PROCREATED )
    // || !PtResizePolicy( widget ) )
        return;

    if ( ( widget->flags & Pt_REALIZED ) &&
         ( ctnr->flags & Pt_AUTO_EXTENT ) )
    {
        ctnr->flags |= Pt_IGNORE_CONSTRAINTS;
        PtMoveResizeWidget( widget, 0 );
        ctnr->flags &= ~Pt_IGNORE_CONSTRAINTS;
    }
}

Child Moved/Resized method

Calls the Child Realized/Unrealized method with the correct parameters:

static void container_child_moved_resized(
     PtWidget_t *widget, PtWidget_t *child,
     PhArea_t *area, PhRect_t *rect,
     PhArea_t *oarea, PhRect_t *orect )
{
    container_child_realized_unrealized( widget, child );
}

Child Destroyed method

None.

Child Setting Resources method

None.

Child Getting Resources method

None.

Child Getting Focus method

None.

Child Losing Focus method

None.

Widget actions

None.

Resource definitions

static const PtRawCallback_t callback = 
{
    Pt_EV_REDIRECTED,   container_callback, NULL
};

static const PtResourceRec_t resources[] = 
{
    { Pt_ARG_AREA, container_modify_area, NULL,
      Pt_ARG_IS_STRUCT( PtWidget_t, area ) },
    { Pt_ARG_DIM, container_modify_area, NULL,
      Pt_ARG_IS_STRUCT( PtWidget_t, area.size ) },
    { Pt_ARG_POS, container_modify_area, NULL,
      Pt_ARG_IS_STRUCT( PtWidget_t, area.pos ) },
    { Pt_ARG_RESIZE_FLAGS, container_modify_area, NULL,
      Pt_ARG_IS_FLAGS( PtWidget_t, resize_flags ) },
    { Pt_ARG_ANCHOR_OFFSETS, container_modify_area, NULL,
      Pt_ARG_IS_STRUCT( PtContainerWidget_t, anchor_offset) },
    { Pt_ARG_ANCHOR_FLAGS, container_modify_area, NULL,
      Pt_ARG_IS_FLAGS( PtContainerWidget_t, anchor_flags ) },
    { Pt_ARG_FOCUS, container_modify, NULL,
      Pt_ARG_IS_POINTER( PtContainerWidget_t, focus ) },
    { Pt_CB_RESIZE, Pt_CHANGE_INVISIBLE, NULL,
      Pt_ARG_IS_CALLBACK_LIST( PtContainerWidget_t, resize ) },
    { Pt_CB_BALLOONS, container_set_balloons, NULL,
      Pt_ARG_IS_LINK( PtContainerWidget_t, balloons ) },
    { Pt_ARG_CONTAINER_FLAGS, container_modify_flags, NULL,
      Pt_ARG_IS_FLAGS( PtContainerWidget_t, flags ) },
    { Pt_ARG_TITLE, container_set_title, NULL,
      Pt_ARG_IS_STRING( PtContainerWidget_t, title ) },
    { Pt_ARG_TITLE_FONT, container_set_title, NULL,
      Pt_ARG_IS_STRING( PtContainerWidget_t, title_font ) },
    { Pt_CB_CHILD_ADDED_REMOVED,Pt_CHANGE_INVISIBLE,NULL,
      Pt_ARG_IS_LINK(PtContainerWidget_t,child_added_removed ) },
};

Functions

container_modify_area()

If area, pos, or dim is being modified, the container's anchors are invalidated and unlocked:

container->flags |= Pt_ANCHORS_INVALID;
container->flags &= ~Pt_ANCHORS_LOCKED;

The Pt_ANCHORS_INVALID bit indicates that the widget can't be anchored using the values in the anchor offsets member until these values are recalculated.

The Pt_ANCHORS_LOCKED bit indicates that the anchor offsets for the container are valid and shouldn't be recalculated due to the change that just occurred. This bit is set when Pt_ARG_ANCHOR_OFFSETS is set. If Pt_ARG_ANCHOR_OFFSETS is set, the anchors are validated and locked. If Pt_ARG_RESIZE_FLAGS is being modified, the anchors are invalidated and the widget is flagged for resize:

widget->flags |= Pt_WIDGET_RESIZE;

container_modify()

static void container_modify( PtWidget_t *widget, 
                              PtArg_t *arg )
{
   PtContainerWidget_t *container =
       (PtContainerWidget_t *)widget;
   PhEvent_t event;

   memset( &event, 0, sizeof( event ) );
   switch( arg->type )
   {
      case Pt_ARG_FOCUS:
         // If the widget is already focused or isn't
         // the immediate child of this container, 
         // do nothing.

         if (( container->focus == 
               (PtWidget_t *)arg->value )
             || ( !arg->value )
             || (((PtWidget_t *)arg->value)->parent != 
                  widget))
               return;

         // otherwise, give the target widget focus.
         PtContainerGiveFocus( (PtWidget_t *)arg->value, 
                               &event );
        if( container->focus && container->focus->flags & Pt_REALIZED )
            PtDamageWidget( container->focus );
   }
}

container_set_balloons()

Registers/deregisters balloons with the container and increments/decrements the container's bal