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 balloon count (container->balloon_count). If the balloon count is nonzero, the balloons_active bit located in container->anchor_flags is set; otherwise, it's cleared.

A raw callback function to check the balloon list is added if the balloon count is nonzero and the balloons_active bit was not set. The callback is removed if the balloon count goes to zero and the balloons_active bit was set.

container_modify_flags()

Container flags are set/cleared. If one of the bits affected was the Pt_AUTO_EXTENT bit, several constraint functions are enabled or disabled and the widget is (potentially) scheduled to have its Extent method executed.

static void
container_modify_flags( PtWidget_t *widget,
                        PtArg_t const *argt )
    {
    PtContainerWidget_t *ctnr =
       (PtContainerWidget_t *)widget;
    int changed;
    unsigned long mask =
       argt->len & ~Pt_CONTAINER_RO_FLAGS;
    changed = ctnr->flags;
    changed ^= ctnr->flags =
       ( ctnr->flags & ~mask ) |
       ( argt->value & mask );

    if( changed & Pt_AUTO_EXTENT )
        {
        if( ctnr->flags & Pt_AUTO_EXTENT )
            {
            ctnr->flags |= Pt_CHILD_REALIZED |
                           Pt_CHILD_UNREALIZED |
                           Pt_CHILD_MOVED_RESIZED;
            widget->flags |= Pt_WIDGET_RESIZE;
            PtSyncWidget( widget );
            }
        }
    }

PtCompound

This class is used for creating widgets whose functionality (in part) is derived from exported subordinate widgets.

Class hierarchy

PtWidget → PtBasic → PtContainer → PtCompound

Class extensions

typedef struct Pt_compound_class {
    PtContainerClass_t      container;
    unsigned short          num_subordinates;
    unsigned short          num_blocked_resources;
    unsigned short          *subordinates;
    unsigned long           *blocked_resources;
} PtCompoundClass_t;

#define Pt_SET_NUM_SUBORDINATES \
    (Pt_ARG_IS_NUMBER(PtCompoundClass_t,num_subordinates))

#define Pt_SET_SUBORDINATES \
    (Pt_ARG_IS_POINTER(PtCompoundClass_t,subordinates)

#define Pt_SET_NUM_BLOCKED_RESOURCES \
    (Pt_ARG_IS_NUMBER(PtCompoundClass_t,num_blocked_resources))

#define Pt_SET_BLOCKED_RESOURCES \
    (Pt_ARG_IS_POINTER(PtCompoundClass_t,blocked_resources)

Pt_SET_NUM_SUBORDINATES

Indicates the number of subordinate widgets to be exported.

Pt_SET_SUBORDINATES

An array of offsets to widget pointers to subordinate widgets. These widgets must be created in the compound widget's Defaults method.

Pt_SET_NUM_BLOCKED_RESOURCES

Indicates the number of resources to block.

Pt_SET_BLOCKED_RESOURCES

An array of resources to block.

Methods

PtCompound defines the class methods described below.

Defaults method

Inherits all defaults from PtContainer.

Initialization method

None.

Extent method

Inherited from PtContainer.

Connection method

None.

Realization method

None.

Draw method

Inherited from PtContainer.

Unrealization method

None.

Destruction method

Destroys the redirected callback lists of exported subordinates having callback resources set on them.

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtContainer.

Calc Opaque Rect method

Inherited from PtBasic.

Widget actions

None.

Resource definitions

None.

Functions

None.

PtGenList

This class is used for creating list widgets.

Class hierarchy

PtWidget → PtBasic → PtContainer → PtCompound → PtGenList

Class extensions

typedef void PtGenListDrawF_t(
        PtWidget_t *widget,
        PtGenListItem_t *item, unsigned index,
        unsigned nitems,
        PhRect_t *where /* Modify *where if needed */
        );

typedef int PtGenListMouseF_t(
        PtWidget_t *wgt,
        PtGenListItem_t *item,
        unsigned index,
        PhPoint_t *where, /* relative to the item, can modify */
        int column,
        PhEvent_t *ev
        );

typedef int PtGenListKeyF_t(
        PtWidget_t *wgt,
        PhEvent_t *ev, PhKeyEvent_t *kev,
        PtGenListItem_t *newcur, unsigned newpos
        );

typedef void PtGenListSelectF_t(
        PtWidget_t *wgt, PtGenListItem_t *item, int pos, int column,
        int nitems, int subtype, PhEvent_t *ev
        );

typedef PtWidget_t *PtGenListInflateF_t(
        PtWidget_t *widget, PtWidget_t *parent,
        PtGenListItem_t *item, unsigned index,
        int column, PhArea_t *area
        );

typedef void PtGenListDrawBackgroundF_t(
        PtWidget_t *widget,
        PhRect_t const *canvas, PhRect_t const *empty
        );

typedef int PtGenListDndCallbackF_t(
        PtWidget_t *widget,
        PtGenListItem_t const *item, int index, PhEvent_t *event,
        unsigned long *pflags, unsigned int *action
        );

typedef const PtGenListItemAttrs_t *PtGenListGetItemAttrsF_t(
        PtWidget_t *widget, PtGenListItem_t const *item
        );

typedef struct Pt_gen_list_widget_class {
    PtCompoundClass_t   compound;
        PtGenListDrawF_t        *list_draw_f;
        PtGenListMouseF_t        *list_mouse_f;
        PtGenListKeyF_t                *list_key_f;
        PtGenListSelectF_t        *list_select_f;
        PtGenListInflateF_t        *list_inflate_f;
        PtGenListDrawBackgroundF_t *list_draw_background_f;
        PtGenListDndCallbackF_t *list_dnd_callback_f;
        PtGenListGetItemAttrsF_t *list_itemattrs_f;
        }
                PtGenListClass_t;

#define Pt_SET_LIST_DRAW_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_draw_f )
#define Pt_SET_LIST_MOUSE_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_mouse_f )
#define Pt_SET_LIST_KEY_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_key_f )
#define Pt_SET_LIST_SELECT_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_select_f )
#define Pt_SET_LIST_INFLATE_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_inflate_f )
#define Pt_SET_LIST_DRAW_BACKGROUND_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_draw_background_f )
#define Pt_SET_LIST_DND_CALLBACK_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_dnd_callback_f )
#define Pt_SET_LIST_ITEMATTRS_F \
        Pt_ARG_IS_POINTER( PtGenListClass_t, list_itemattrs_f )

Methods

PtGenList defines the class methods described below.

Defaults method

        widget->flags |= Pt_HIGHLIGHTED | Pt_ETCH_HIGHLIGHT |
                         Pt_SET | Pt_GETS_FOCUS | Pt_FOCUS_RENDER;
        widget->eflags &= ~Pt_DAMAGE_ON_FOCUS;
        widget->resize_flags &= ~Pt_RESIZE_XY_BITS;
        widget->border_width = 1; //2;
        list->columns = & list->dfltcol;
        list->ncolumns = 1;
        list->flags = Pt_LIST_SCROLLBAR_AUTORESIZE |
                      Pt_LIST_VSCROLLBAR_AS_REQUIRED |
                      Pt_LIST_BALLOONS_IN_COLUMNS;
        set_selmode( list, list->sel_mode = Pt_BROWSE_MODE );
        list->scroll_rate = 2;
        list->selection_fill_color = PgRGB( 142, 162, 155 );
        list->selection_text_color = Pg_WHITE;
        list->balloon_bg = Pg_BALLOONCOLOR;
        list->balloon_fg = Pg_BLACK;
        list->font = Pt_GET_MAGIC_FONT_NAME( TextFont09 );
        list->dnd_selection_color = PgRGB( 216, 216, 216 );
        getfontsize( list );

        basic->margin_width =
        basic->margin_height = 0;
        basic->flags = Pt_ALL_ETCHES | Pt_OPAQUE_ETCHES |
                       Pt_ALL_OUTLINES /*| Pt_LEFT_INLINE*/ |
                       Pt_FLAT_FILL;
        basic->inline_color = Pg_GREY;
        basic->fill_color = PgGrey( 244 );
        widget->eflags &= ~Pt_DAMAGE_ON_FOCUS;
        list->slider_width = SCROLLBAR_DEFAULT_WIDTH;
        list->max_top = list->top_item = 1;

Initialization method

None.

Extent method

If a PtDivider widget is the child, the Extent method:

• calls the Extent method of PtDivider via PtExtentWidget()
• adjusts the size of the PtDivider widget according to the resize policy and the Pt_LIST_SNAP flag

Then the Extent method of PtCompound is invoked via PtSuperClassExtent().

Connection method

None.

Realization method

Realizes the scrollbar if necessary and registers a balloon callback with the parent.

Draw method

Renders the widget's border, margins, and (possibly) background. Then the List Draw method is called to draw the list.

Unrealization method

Deregisters a balloon callback with the parent.

Destruction method

None.

Got Focus method

If the Pt_FOCUS_RENDER flag is set, the Got Focus method damages the current item (see “Current item” in the description of PtGenList in the Widget Reference). If the Pt_SELECTION_MODE_AUTO flag is set but the Pt_SELECTION_MODE_NOFOCUS flag isn't set and no items are selected, the current item is selected. Then the Got Focus method of PtCompound is invoked via PtSuperClassGotFocus().

Lost Focus method

If necessary, the current item is damaged. Then the Lost Focus method of PtCompound is invoked via PtSuperClassLostFocus().

Calc Opaque Rect method

Inherited from PtBasic.

Child Created method

Sets the child redirector function to PtCompoundRedirect() via the Pt_SET_CHILD_REDIRECT_F manifest defined by PtContainer. This prevents the list widget from having more than one PtDivider child.

Child Realized method

If the child isn't the scrollbar (it's a divider), the Child Realized method:

• Sets list->divider to the widget pointer of the child.
• Adjusts the top margin.
• Sets the orientation of the child to horizontal.
• Sets the child's Pt_ARG_DIVIDER_OFFSET resource and the Pt_CALLBACKS_ACTIVE flag.
• Copies the Pt_ARG_DIVIDER_SIZES resource of the child to the Pt_ARG_LIST_COLUMN_POS resource of the list widget.
• Attaches a function to the Pt_CB_DIVIDER_DRAG callback list.

Child Moved/Resized method

If the child is a divider (i.e. list->divider), the Child Moved/Resized method sets the divider's Pt_ARG_DIVIDER_OFFSET resource and adjusts the top margin of the list widget.

Child Unrealized method

If the child is the same as list->divider, the Child Unrealized method adjusts the top margin, removes the callback, and sets list->divider to NULL.

Child Destroyed method

Sets the child redirector function to a private function that accepts a PtDivider child only.

Child Setting Resources method

Inherited from PtContainer.

Child Getting Resources method

Inherited from PtContainer.

Child Getting Focus method

Inherited from PtContainer.

Child Losing Focus method

Inherited from PtContainer.

List Draw method

None.

List Mouse method

None.

List Key method

None.

List Select method

None.

List Inflate method

None.

List Attributes method

None.

Widget actions

PtGenList is sensitive to the following events:

• Ph_EV_KEY
• Ph_EV_BUT_PRESS
• Ph_EV_PTR_MOTION_BUTTON
• Ph_EV_BUT_RELEASE
• Ph_EV_BUT_REPEAT

The callback function invokes the List Key or List Mouse method and performs the selection.

---

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, PtGenList behavior for that event won't occur unless you invoke PtGenList's raw handlers within the callback prior to returning. This can be done via PtSuperClassRawEvent().

---

Resource definitions

static const PtResourceRec_t resources[] =
{
    {Pt_ARG_AREA,gl_arg_resize, NULL,
     Pt_ARG_IS_STRUCT( PtWidget_t, area )
    },
    {Pt_ARG_DIM,gl_arg_resize, NULL,
     Pt_ARG_IS_STRUCT( PtWidget_t, area.size )
    },
    {Pt_ARG_FLAGS,arg_wflags, NULL,
     Pt_ARG_IS_FLAGS( PtWidget_t, flags )
    },
    {Pt_ARG_POS,gl_arg_resize, NULL,
     Pt_ARG_IS_STRUCT( PtWidget_t, area.pos )
    },
    {Pt_ARG_COLOR,arg_txtcolor, NULL,
     Pt_ARG_IS_COLOR( PtBasicWidget_t, color )
    },
    {Pt_ARG_MARGIN_HEIGHT,gl_arg_resize, NULL,
     Pt_ARG_IS_NUMBER( PtGenListWidget_t, marg_height )
    },
    {Pt_ARG_MARGIN_WIDTH,gl_arg_resize, NULL,
     Pt_ARG_IS_NUMBER( PtGenListWidget_t, marg_width )
    },
    {Pt_ARG_LIST_FLAGS,gl_arg_flags, NULL,
     Pt_ARG_IS_FLAGS( PtGenListWidget_t, flags )
    },
    {Pt_ARG_LIST_FONT,arg_font, NULL,
     Pt_ARG_IS_STRING( PtGenListWidget_t, font )
    },
    {Pt_ARG_SCROLLBAR_WIDTH,gl_arg_resize, NULL,
     Pt_ARG_IS_NUMBER( PtGenListWidget_t, slider_width )
    },
    {Pt_ARG_SELECTION_MODE,arg_selmode, NULL,
     Pt_ARG_IS_NUMBER( PtGenListWidget_t, sel_mode )
    },
    {Pt_ARG_TOP_ITEM_POS,arg_top_pos, NULL,
     Pt_ARG_IS_NUMBER( PtGenListWidget_t, top_item  )
    },
    {Pt_ARG_SCROLLBAR,gl_arg_flags, NULL,
     Pt_ARG_IS_BOOLEAN( PtGenListWidget_t, flags ),
     Pt_LIST_VSCROLLBAR_ALWAYS
    },
    {Pt_ARG_SELECTION_FILL_COLOR, arg_selfillcolor, NULL,
     Pt_ARG_IS_COLOR( PtGenListWidget_t, selection_fill_color )
    },
    {Pt_ARG_SELECTION_TEXT_COLOR, arg_seltxtcolor, NULL,
     Pt_ARG_IS_COLOR( PtGenListWidget_t, selection_text_color)
    },
    {Pt_ARG_LIST_SB_RES, arg_setsb, arg_getsb
    },
    {Pt_ARG_LIST_COLUMN_POS, arg_columns, NULL,
     Pt_ARG_IS_ARRAY( PtGenListWidget_t, columns ),
     Pt_ARG_IS_NUMBER( PtGenListWidget_t, ncolumns )
    },
    {Pt_ARG_SB_FILL_COLOR, arg_setsbcolor, arg_getsbcolor,0
    },
    {Pt_ARG_SB_ARROW_COLOR, arg_setsbpencolor, arg_getsbpencolor,0
    },
    {Pt_ARG_SB_TROUGH_COLOR, arg_setsbtroughcolor, arg_getsbtroughcolor,0
    },

};

Functions

static void arg_resize()

This function:

• adjusts the number of displayed items
• resizes the scrollbar
• adjusts the Pt_ARG_DIVIDER_OFFSET resource of the widget pointed to by list->divider

static void arg_font()

This function:

• allocates a copy of the new font name and frees the old string
• stores the height of the new font in list->font_height

static void arg_top_pos()

This function:

• calculates a new range of displayed items
• blits some of the currently visible items to their new positions (blits only the items that will remain visible after the change)
• adjusts the scrollbar position
• invokes the Pt_CB_SCROLL_MOVE callback

static void arg_selmode()

This function:

• clears the current selection
• if the new value is valid, sets list->sel_mode, list->sel_xmode, and list->sel_flags

static void arg_flags()

For Pt_ARG_LIST_FLAGS, this function:

• adjusts the Pt_GETS_FOCUS flag of the scrollbar if the Pt_LIST_SCROLLBAR_GETS_FOCUS flag is changed
• adjusts list->sel_xmode and list->sel_flags if the Pt_LIST_NON_SELECT flag is changed

static void arg_setsb()

This function:

• checks if allowed resources were specified
• calls PtSetResources() for the scrollbar

static void arg_getsb()

Calls PtGetResources() for the scrollbar.

static void arg_columns()

This function:

• saves the new value
• damages the appropriate portions of the widget

For more information, see the chapter on Creating a List Widget.

PtGenTree

This class is used for creating tree widgets.

Class hierarchy

PtWidget → PtBasic → PtContainer → PtCompound → PtGenList → PtGenTree

Class extensions

typedef void PtGenTreeDrawItemF_t(
    PtWidget_t *widget, PtGenTreeItem_t *item,
    PhRect_t const *where, int lmargin, int rmargin
    );

typedef int PtGenTreeItemStateF_t(
    PtWidget_t *widget, PtGenTreeItem_t *item,
    PhEvent_t *event, int reason
    );

typedef struct Pt_gen_tree_widget_class {
    PtGenListClass_t        list;
    PtGenTreeDrawItemF_t    *tree_draw_item_f;
    PtGenTreeItemStateF_t   *tree_state_f;
    }
        PtGenTreeClass_t;

#define Pt_SET_TREE_DRAW_F \
        Pt_ARG_IS_POINTER( PtGenTreeClass_t, tree_draw_item_f )
#define Pt_SET_TREE_STATE_F \
        Pt_ARG_IS_POINTER( PtGenTreeClass_t, tree_state_f )

Methods

PtGenTree defines the class methods described below.

Defaults method

tree->flags = Pt_TREE_HAS_BUTTONS |
              Pt_TREE_TO_LEFT | Pt_TREE_TO_RIGHT |
              Pt_TREE_INDENT_BUTTONS |
              Pt_TREE_SHOW_CONNECTORS;
tree->list.gflags = Pt_GEN_LIST_SHOW_DAMAGED |
                    Pt_GEN_LIST_ITEM_BACKGROUND;
tree->list.selection_fill_color = PgRGB( 142, 162, 155 );
tree->line_spacing = 3;
tree->line_color = PgRGB( 239, 239, 239 );
tree->margin_color = PgRGB( 225, 225, 225 );

Initialization method

None.

Extent method

Inherited from PtGenList.

Connection method

None.

Realization method

None.

Draw method

Inherited from PtGenList.

Unrealization method

None.

Destruction method

None.

Got Focus method

Inherited from PtGenList.

Lost Focus method

Inherited from PtGenList.

Calc Opaque Rect method

Inherited from PtBasic.

Child Created method

Inherited from PtGenList.

Child Realized method

Inherited from PtGenList.

Child Moved/Resized method

Inherited from PtGenList.

Child Unrealized method

Inherited from PtGenList.

Child Destroyed method

Inherited from PtGenList.

Child Setting Resources method

Inherited from PtContainer.

Child Getting Resources method

Inherited from PtContainer.

Child Getting Focus method

Inherited from PtContainer.

Child Losing Focus method

Inherited from PtContainer.

List Draw method

For each visible item that has the Pt_LIST_ITEM_DAMAGED flag set, the List Draw method calls the Tree Draw Item method and draws the tree ornaments.

List Mouse method

Invokes the Pt_CB_GEN_TREE_INPUT callback list. Depending on the result of the callback and the pointer position, the List Mouse method returns Pt_CONTINUE, returns Pt_END, or calls PtGenTreeCollapse() or PtGenTreeExpand() (see the Photon Widget Reference) and returns Pt_END.

List Key method

Invokes the Pt_CB_GEN_TREE_INPUT callback list. Depending on the result of the callback and the key code, the List Key method returns Pt_CONTINUE, returns Pt_END, or calls PtGenTreeCollapse() or PtGenTreeExpand() (see the Photon Widget Reference) and returns Pt_HALT.

Tree Draw Item method

None.

Tree Item State method

None.

Widget actions

None.

Resource definitions

static const PtResourceRec_t resources[] = {
    {   Pt_ARG_TREE_FLAGS, arg_flags, NULL,
        Pt_ARG_IS_FLAGS( PtGenTreeWidget_t, flags )
        },
    {   Pt_ARG_TREE_LINE_SPACING, arg_line_spacing, NULL,
        Pt_ARG_IS_NUMBER( PtGenTreeWidget_t, line_spacing )
        },
    {   Pt_ARG_TREE_LINE_COLOR, Pt_CHANGE_RESIZE_REDRAW, NULL,
        Pt_ARG_IS_NUMBER( PtGenTreeWidget_t, line_color )
        },
    {   Pt_ARG_TREE_MARGIN_COLOR, Pt_CHANGE_RESIZE_REDRAW, NULL,
        Pt_ARG_IS_NUMBER( PtGenTreeWidget_t, margin_color )
        },
    {   Pt_CB_GEN_TREE_INPUT, Pt_CHANGE_INVISIBLE, NULL,
        Pt_ARG_IS_CALLBACK( PtGenTreeWidget_t, input_cb )
    }   };

Functions

static void arg_flags()

This function:

• Adjusts list->gflags if the Pt_TREE_TO_RIGHT flag has changed.
• Damages the widget or marks it for resizing.

For more information, see the chapter on Creating a Tree Widget.

PtLabel

The PtLabel class provides fundamental multiline-text string and image handling.

Class hierarchy

PtWidget → PtBasic → PtLabel

Methods

PtLabel defines the class methods described below.

Defaults method

widget->flags |= Pt_FOCUS_RENDER;
widget->resize_flags |= Pt_RESIZE_XY_AS_REQUIRED;
label->basic.flags = Pt_ALL_ETCHES | Pt_ALL_BEVELS |
                     Pt_FLAT_FILL;
label->basic.fill_color = Pg_TRANSPARENT;
label->font = strdup( "TextFont09" );
label->flags |= Pt_LABEL_SELECT_SHIFT;
label->uline1 = Pg_BLACK;
label->uline2 = Pg_TRANSPARENT;
label->uline_type            =(unsigned short) Pt_NO_ULINE;
label->type                  = Pt_Z_STRING;
label->text_image_spacing    = 2;
label->h_alignment           = Pt_LEFT;
label->v_alignment           = Pt_CENTER;
label->string                = strdup("");
label->inflate_f             = PtInflateBalloon;
label->balloon_fill_color    = Pg_BALLOONCOLOR;
label->balloon_color         = Pg_BLACK;
label->balloon_text          = strdup("");
if ( _Ph_->draw_context->gin.cmd_buf_limit < 4096 )
    PgSetDrawBufferSize(4096);

Initialization method

None.

Extent method

Determines the required canvas size based on the widget's text string or image data in conjunction with label->type (Pt_Z_STRING, Pt_TEXT_IMAGE ), margins, etc. The Extent method also takes into account multiple lines of text and underlining.

Connection method

If label->flags has the Pt_SHOW_BALLOON flag set, a balloon callback is attached to the parent widget.

Realization method

Inherited from PtBasic.

Draw method

Calls the Draw method of PtBasic via PtSuperClassDraw(). Draws the text in the label using the specified font, color, etc.

Unrealization method

If this label has a balloon displayed (label->balloon_widget != NULL), that widget is destroyed. If label->flags has the Pt_SHOW_BALLOON flag set, it detaches the balloon callback from the parent.

Got focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

Calc Opaque Rect method

If label->type is Pt_Z_STRING, the Calc Opaque Rect method is called via PtSuperClassCalcOpaque().

If label->type is Pt_IMAGE, label->flags has its Pt_OPAQUE flag set.

If label->type is Pt_BITMAP and label->data->image->type is Pg_BITMAP_BACKFILL, the Pt_OPAQUE bit of widget->flags is set.

Widget actions

None.

Resource definitions

    static const PtResourceRec_t resources[] =
    {
        { Pt_ARG_BALLOON_TEXT, (void*)PtModifyBallonText, NULL,
          Pt_ARG_IS_STRING( PtLabelWidget_t, balloon_text ) },
        { Pt_ARG_FLAGS, set_flags, NULL,
          Pt_ARG_IS_FLAGS (PtWidget_t, flags) },
        { Pt_ARG_HORIZONTAL_ALIGNMENT, Pt_CHANGE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, h_alignment ) },
    { Pt_ARG_LABEL_IMAGE, Pt_CHANGE_CANVAS_REDRAW, NULL,
          Pt_ARG_IS_IMAGE( PtLabelWidget_t, data ) },
        { Pt_ARG_LABEL_FLAGS, label_modify_flags, NULL,
          Pt_ARG_IS_FLAGS( PtLabelWidget_t, flags ) },
        { Pt_ARG_LABEL_TYPE, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, type) },
        { Pt_ARG_MARGIN_BOTTOM, Pt_CHANGE_CANVAS_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, margin_bottom ) },
        { Pt_ARG_MARGIN_LEFT, Pt_CHANGE_CANVAS_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, margin_left ) },
        { Pt_ARG_MARGIN_RIGHT, Pt_CHANGE_CANVAS_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, margin_right ) },
        { Pt_ARG_MARGIN_TOP, Pt_CHANGE_CANVAS_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, margin_top ) },
        { Pt_ARG_SELECT_SHIFT, Pt_CHANGE_REDRAW, NULL,
          Pt_ARG_IS_BOOLEAN( PtLabelWidget_t, flags ),
          Pt_LABEL_SELECT_SHIFT },
        { Pt_ARG_TEXT_FONT, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_STRING( PtLabelWidget_t, font ) },
        { Pt_ARG_TEXT_STRING, PtModifyLabelString, NULL,
          Pt_ARG_IS_STRING( PtLabelWidget_t, string ) },
        { Pt_ARG_UNDERLINE1, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, uline1) },
        { Pt_ARG_UNDERLINE2, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, uline2) },
        { Pt_ARG_UNDERLINE_TYPE, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, uline_type) },
        { Pt_ARG_VERTICAL_ALIGNMENT, Pt_CHANGE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, v_alignment ) },
        { Pt_ARG_BALLOON_POSITION, balloon_position, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, balloon_pos ) },
        { Pt_ARG_LABEL_BALLOON, Pt_CHANGE_INVISIBLE, NULL,
          Pt_ARG_IS_POINTER( PtLabelWidget_t, inflate_f) },
        { Pt_ARG_ACCEL_KEY, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_STRING( PtLabelWidget_t, accel_key ) },
        { Pt_ARG_BALLOON_FILL_COLOR, Pt_CHANGE_INVISIBLE, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, balloon_fill_color ) },
        { Pt_ARG_BALLOON_COLOR, Pt_CHANGE_INVISIBLE, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, balloon_color ) },
        { Pt_ARG_LINE_SPACING, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, line_spacing ) },
        { Pt_ARG_TEXT_IMAGE_SPACING, Pt_CHANGE_RESIZE_REDRAW, NULL,
          Pt_ARG_IS_NUMBER( PtLabelWidget_t, text_image_spacing ) },
    };

Functions

static int label_modify_flags( PtWidget_t *widget,
                               PtArg_t const *argt );

If the Pt_SHOW_BALLOON flag is being set, the balloon callback is attached to the parent. If the Pt_SHOW_BALLOON flag is being cleared, the balloon callback is detached from the parent. The value of label->flags is based on argt->value and argt->len. This is typically done as follows:

label->flags = (label->flags & ~argt->len) | argt->value;

int PtModifyLabelString( PtWidget_t *widget,
                         PtArg_t const *argt );

This frees the current string, allocates enough space for the new string, copies in the new string, flags the widget to be resized (widget->flags |= Pt_WIDGET_RESIZE;), and damages the widget.

If a balloon is displayed and Pt_ARG_BALLOON_TEXT is not set, the balloon is destroyed and a new balloon is inflated with the new string. If label->flags has the Pt_BALLOON_AS_REQUIRED bit set, the new balloon is created only if the label is clipped by its parent.

static int PtModifyBalloonText( PtWidget_t *widget,
                                PtArg_t const *arg );

This frees the current balloon text, allocates enough space for the new balloon text and copies it in. If a balloon is currently displayed, the balloon is destroyed and a new balloon is inflated with the new text. If label->flags has the Pt_BALLOON_AS_REQUIRED bit set, the new balloon is created only if the label is clipped by its parent.

PtGraphic

This class provides standard graphic resources such as Pt_ARG_POINTS and Pt_ARG_ORIGIN.

Class hierarchy

PtWidget → PtBasic → PtGraphic

Methods

PtGraphic defines the class methods described below.

Defaults method

graphic->line_cap             = Pg_BUTT_CAP;
graphic->line_join            = Pg_MITER_JOIN;
graphic->basic.margin_height  = 0;
graphic->basic.margin_width   = 0;
graphic->basic.fill_color     = Pg_TRANSPARENT;

Initialization method

None.

Extent method

Determines the render rectangle for the graphic widget, given the area, point array, and current settings of graphic flags.

Connection method

None.

Realization method

None.

Draw method

Inherited from PtBasic.

Unrealization method

None.

Destruction method

None.

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

Calc Opaque Rect method

Inherited from PtBasic.

Widget actions

None.

Resource definitions

static const PtResourceRec_t resources[] = {
    Pt_ARG_AREA,            graphic_modify_area, 0,
        Pt_ARG_IS_STRUCT( PtWidget_t, area ), 0,
    Pt_ARG_DIM,         graphic_modify_area, 0,
        Pt_ARG_IS_STRUCT( PtWidget_t, area.size ) |
        Pt_ARG_PARM( sizeof( PhPoint_t ) ), 0,
    Pt_ARG_DASH_LIST,   Pt_CHANGE_REDRAW, 0,
        Pt_ARG_IS_ARRAY( PtGraphicWidget_t, dash_list ),
        Pt_ARG_IS_NUMBER( PtGraphicWidget_t, dash_len ),
    Pt_ARG_GRAPHIC_FLAGS,   Pt_CHANGE_RESIZE, 0,
        Pt_ARG_IS_FLAGS( PtGraphicWidget_t, flags ),0,
    Pt_ARG_LINE_WIDTH,  Pt_CHANGE_RESIZE_REDRAW, 0,
        Pt_ARG_IS_NUMBER( PtGraphicWidget_t, line_width ), 0,
    Pt_ARG_LINE_JOIN,   Pt_CHANGE_REDRAW, 0,
        Pt_ARG_IS_NUMBER( PtGraphicWidget_t, line_join ), 0,
    Pt_ARG_LINE_CAP,    Pt_CHANGE_REDRAW, 0,
        Pt_ARG_IS_NUMBER( PtGraphicWidget_t, line_cap ), 0,
    Pt_ARG_ORIGIN,  Pt_CHANGE_RESIZE_REDRAW, 0,
        Pt_ARG_IS_STRUCT( PtGraphicWidget_t, origin ),0,
    Pt_ARG_POINTS,  Pt_CHANGE_RESIZE_REDRAW, 0,
        Pt_ARG_IS_ARRAY( PtGraphicWidget_t, point_array),
        Pt_ARG_IS_NUMBER( PtGraphicWidget_t, npoints),
    Pt_CB_RESCALE,  Pt_CHANGE_INVISIBLE, 0,
        Pt_ARG_IS_CALLBACK_LIST( PtGraphicWidget_t, rescale ), 0,
    Pt_ARG_DASH_SCALE,  Pt_CHANGE_REDRAW, 0,
        Pt_ARG_IS_NUMBER( PtGraphicWidget_t, dash_scale ), 0,
};

Functions

graphic_modify_area()

Updates the widget's area or dimension and invokes the Pt_CB_RESCALE callback.

PtGauge

This class provides standard gauge resources such as maximum, minimum, and orientation.

Class hierarchy

PtWidget → PtBasic → PtGauge

Methods

PtGauge defines the class methods described below.

Defaults method

gauge->font = strdup("TextFont09");
gauge->flags = Pt_GAUGE_HORIZONTAL;
gauge->maximum = 100;

Initialization method

None.

Extent method

Inherited from PtBasic.

Connection method

None.

Realization method

None.

Draw method

Inherited from PtBasic.

Unrealization method

None.

Destruction method

None.

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

Calc Opaque Rect method

Inherited from PtBasic

Widget actions

None.

Resource definitions

static const PtResourceRec_t resources[] =
{
    { Pt_ARG_GAUGE_FLAGS, Pt_CHANGE_INVISIBLE, NULL,
      Pt_ARG_IS_FLAGS( PtGaugeWidget_t, flags ),
      Pt_GAUGE_RO_FLAGS },
    { Pt_ARG_GAUGE_FONT, Pt_CHANGE_CANVAS_REDRAW, NULL,
      Pt_ARG_IS_STRING( PtGaugeWidget_t, font ) },
    { Pt_ARG_GAUGE_MINIMUM, Pt_CHANGE_CANVAS_REDRAW, NULL,
      Pt_ARG_IS_NUMBER( PtGaugeWidget_t, minimum ) },
    { Pt_ARG_GAUGE_MAXIMUM, Pt_CHANGE_CANVAS_REDRAW, NULL,
      Pt_ARG_IS_NUMBER( PtGaugeWidget_t, maximum ) },
    { Pt_ARG_GAUGE_VALUE, Pt_CHANGE_REDRAW, NULL,
      Pt_ARG_IS_NUMBER( PtGaugeWidget_t, value ) },
    { Pt_ARG_ORIENTATION, Pt_CHANGE_RESIZE_REDRAW, NULL,
      Pt_ARG_IS_BOOLEAN( PtGaugeWidget_t, flags ),
      Pt_GAUGE_HORIZONTAL },
    { Pt_ARG_GAUGE_VALUE_PREFIX, Pt_CHANGE_CANVAS_REDRAW, NULL,
      Pt_ARG_IS_STRING( PtGaugeWidget_t, prefix ) },
    { Pt_ARG_GAUGE_VALUE_SUFFIX, Pt_CHANGE_CANVAS_REDRAW, NULL,
      Pt_ARG_IS_STRING( PtGaugeWidget_t, suffix ) },
    { Pt_ARG_GAUGE_H_ALIGN, Pt_CHANGE_CANVAS, NULL,
      Pt_ARG_IS_NUMBER( PtGaugeWidget_t, h_alignment ) },
    { Pt_ARG_GAUGE_V_ALIGN, Pt_CHANGE_CANVAS, NULL,
      Pt_ARG_IS_NUMBER( PtGaugeWidget_t, v_alignment ) },
};

Functions

None.