`PtWidget`

Superclass for all widgets

Class hierarchy:

PtWidget

For more information, see the diagram of the widget hierarchy.

Description:

PtWidget is the fundamental superclass. All widgets belong to a subclass of PtWidget.

New resources:

Resource	C type	Pt type	Default
Pt_ARG_AREA	`PhArea_t`	Struct	0,0,0,0
Pt_ARG_BITMAP_CURSOR	`PhCursorDef_t *`	Alloc	NULL
Pt_ARG_BORDER_WIDTH	`unsigned short`	Scalar	2
Pt_ARG_CURSOR_COLOR	`PgColor_t`	Scalar	Ph_CURSOR_DEFAULT_COLOR
Pt_ARG_CURSOR_TYPE	`unsigned short`	Scalar	Ph_CURSOR_INHERIT
Pt_ARG_DATA	`void *`	Alloc	NULL
Pt_ARG_DIM	`PhDim_t`	Struct	0,0
Pt_ARG_EFLAGS	`unsigned short`	Flag	0
Pt_ARG_FLAGS	`long`	Flag	0
Pt_ARG_HELP_TOPIC	`char *`	String	NULL
Pt_ARG_POS	`PhPoint_t`	Struct	0,0
Pt_ARG_RESIZE_FLAGS	`long`	Flag	0
Pt_ARG_USER_DATA	`void *`	Alloc	NULL
Pt_CB_BLOCKED	`PtCallback_t *`	Link	NULL
Pt_CB_DESTROYED	`PtCallback_t *`	Link	NULL
Pt_CB_HOTKEY	`PtHotkeyCallback_t *`	Link	NULL
Pt_CB_RAW	`PtRawCallback_t *`	Link	NULL
Pt_CB_REALIZED	`PtCallback_t` *	Link	NULL
Pt_CB_UNREALIZED	`PtCallback_t` *	Link	NULL

Pt_ARG_AREA

C type	Pt type	Default
`PhArea_t`	Struct	0,0,0,0

The x, y, height, and width values for the widget. This resource isn't displayed in PhAB; PhAB sets it automatically when you move or size the widget.

Pt_ARG_BITMAP_CURSOR

C type	Pt type	Default
`PhCursorDef_t *`	Alloc	NULL

Defines bitmaps for the cursor when the cursor type (Pt_ARG_CURSOR_TYPE) is set to Ph_CURSOR_BITMAP.

The PhCursorDef_t structure is defined as follows:

typedef struct Ph_cursor_def {
    PhRegionDataHdr_t   hdr;
    PhPoint_t           size1;
    PhPoint_t           offset1;
    PgColor_t           color1;
    char                bytesperline1;
    PhPoint_t           size2;
    PhPoint_t           offset2;
    PgColor_t           color2;
    char                bytesperline2;
    char                Spare[14];
    char                images[1];
} PhCursorDef_t;

The members are:

hdr: A pointer to the region data header, which is set automatically by the widget. For information about this structure, see PhRegionDataHdr_t in the Photon Library Reference.
size1: The dimensions of the first bitmap plane, in pixels.
offset1: The position of the upper-left corner of the first plane of the bitmap, relative to the hot spot.
color1: The color of the first bitmap plane.
bytesperline1: The number of bytes per line for the first bitmap plane.
size2: The dimensions of the second bitmap plane, in pixels.
offset2: The position of the upper-left corner of the second plane of the bitmap, relative to the hot spot.
color2: The color of the second bitplane. You can have more than two bit planes.
bytesperline2: The number of bytes per line for the second bitmap plane.
images: The bitmap image data, as a series of 1-bit-per-pixel planes.

This resource can't be edited in PhAB. You can draw the cursor as a PtBitmap widget and have the application turn it into a PhCursorDef_t structure at runtime. For example:

PtArg_t args[2];

ApDBase_t *db = ApOpenDBase( ABM_db );
ApBitmap_t *ab = ApGetBitmapRes( bmpdb, "bitmap" );
unsigned len = sizeof(*d) + 2 * BMP_SIZE;
PhCursorDef_t *d = malloc( len );

memset( d, 0, sizeof(*d) );
d->size1.x = d->size2.x = BMP_WIDTH;
d->size1.y = d->size2.y = BMP_HEIGHT;
d->bytesperline1 = d->bytesperline2 = BMP_BPL;
d->color1 = ab->colors[0];
d->color2 = ab->colors[1];
memcpy( d->images, ab->data[0], BMP_SIZE );
memcpy( d->images + BMP_SIZE, ab->data[1], BMP_SIZE );
PtSetArg( &args[0], Pt_ARG_CURSOR_TYPE, Ph_CURSOR_BITMAP , 0 );
PtSetArg( &args[2], Pt_ARG_BITMAP_CURSOR, d, len );
PtSetResources( ABW_base, 2, args );
free( d );

Pt_ARG_BORDER_WIDTH

C type	Pt type	Default
`unsigned short`	Scalar	2

The thickness of the widget's border. This must not exceed 15 pixels.

Pt_ARG_CURSOR_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Ph_CURSOR_DEFAULT_COLOR

The color of the pointer when it's inside the widget.

Pt_ARG_CURSOR_TYPE

C type	Pt type	Default
`unsigned short`	Scalar	Ph_CURSOR_INHERIT

The type of cursor:

Ph_CURSOR_INHERIT: Inherit the cursor, not from the class hierarchy, but from the family hierarchy, that is, from the way your application nests the widgets. The cursor might even be inherited from the Photon server itself.
Ph_CURSOR_BITMAP: Use the bitmap stored in Pt_ARG_BITMAP_CURSOR for the cursor.

By default, bitmap cursors aren't inherited by a widget's child regions. To change this, set Pt_ARG_CURSOR_TYPE to:

Ph_CURSOR_BITMAP & ~Ph_CURSOR_NO_INHERIT

For other cursor definitions, see <photon/PhCursor.h>.

Pt_ARG_DATA

C type	Pt type	Default
`void *`	Alloc	NULL

This resource is used internally by the Photon libraries as well as by compound widgets. It isn't displayed in PhAB. For more information, see the Building Custom Widgets guide.

If you want to store arbitrary data in a widget, use its Pt_ARG_USER_DATA resource.

Pt_ARG_DIM

C type	Pt type	Default
`PhDim_t`	Struct	0,0

The height and width values for the widget.

This resource isn't displayed in PhAB; PhAB sets it automatically when you size the widget.

Pt_ARG_EFLAGS

C type	Pt type	Default
`unsigned short`	Flag	0

Extended flags inherited by all widgets:

Pt_CONSUME_EVENTS: The widget will consume any event encountered whether or not an action was performed as a result of that event.
Pt_INTERNAL_HELP: Help information for the widget is displayed in a balloon, not in the Helpviewer. See the chapter on Context-Sensitive Help in the Photon Programmer's Guide.
Pt_DAMAGE_PARENT: If the widget is damaged for any reason, propagate the damage to its parent.

Pt_ARG_FLAGS

C type	Pt type	Default
`long`	Flag	0

Common flags used by all widgets. Except for those indicated as read-only, these flags are all read/write. Possible values:

Pt_CALLBACKS_ACTIVE

For a few widgets, setting resources will cause relevant callbacks to be invoked if this bit is set. Otherwise callbacks are not invoked as a result of setting resources. If a callback relies on this flag, its description says so explicitly.

For example, if this bit is set for a PtDivider and you use PtSetResources() to change the size of one of its children, the Pt_CB_DIVIDER_DRAG callback is invoked.

Pt_ALL_BUTTONS

Indicates that any mouse button can activate the widget. Default is the left button only.

Pt_AUTOHIGHLIGHT

Causes the widget to highlight and get focus when the cursor enters its extent, and to unhighlight and lose focus when the cursor leaves.

Pt_BLOCKED

Prevents the widget and all its non-window-class children from interacting with Photon events.

Pt_CLEAR (read-only)

Prevents the widget's brothers-in-front from intersecting with its extent.

Pt_CLIP_HIGHLIGHT

Clips the corners of the highlighting rectangle.

Pt_DAMAGED (read-only)

Indicates that the widget requires repair.

Pt_DAMAGE_FAMILY (read-only)

Indicates that the widget and all its children will be repaired.

Pt_DELAY_REALIZE

Prevents the widget from becoming realized unless it's explicitly realized with PtRealizeWidget().

Pt_DESTROYED (read-only)

The widget has been marked for destruction.

Pt_ETCH_HIGHLIGHT

Highlights the widget with an etched-line style (normally, a beveled rectangle is used).

Pt_FREE_MEMORY

Indicates whether or not the widget may free memory associated with any of its pointers. For example, if this flag is set for a PtLabel widget with an image structure and you destroy the widget, the library frees the image memory as well as the label's image structure.

Using this bit might cause problems if, for example, more than one widget uses the same image. It's better to use the image's flags to indicate which of the image's allocated members should be freed. For more information, see PhImage_t in the Photon Library Reference.

Pt_FOCUS_RENDER

Draws a dotted line around the widget when it gets focus.

Pt_GETS_FOCUS

Allows the widget to be granted focus when appropriate.

Pt_GHOST

The widget is dimmed. Setting this flag doesn't affect the widget's behavior, just its appearance. The simplest way to disable the widget is to set the Pt_BLOCKED flag in this resource.

Pt_HIGHLIGHTED

Highlights the widget with a beveled or etched rectangle. The appearance of the rectangle depends on the Pt_ARG_BORDER_WIDTH, Pt_ARG_TOP_BORDER_COLOR, and Pt_ARG_BOT_BORDER_COLOR resources.

Pt_IN_FLUX (read-only)

Indicates that a call to PtContainerHold() has been made on the widget.

Pt_MENUABLE

The widget will respond to right mouse clicks (i.e. enables PtBasic's Pt_CB_MENU callback.

Pt_MENU_BUTTON

Indicates that the widget is a menu item.

Pt_OBSCURED (read-only)

Indicates that the widget is completely covered by one other widget, or it's completely beyond its parent container's canvas.

Pt_OPAQUE (read-only)

Indicates that this widget completely obscures everything behind it and inside its extent.

Pt_PROCREATED (read-only)

Indicates that the widget is a procreated child of a compound widget.

Pt_REALIZED (read-only)

Indicates that the widget is realized.

Pt_REALIZING (read-only)

Indicates that the widget is in the process of being realized.

Pt_REGION

Forces the widget to have a region.

Pt_SELECTABLE

Indicates that the user can select (repeat, arm, disarm, and activate) this widget. The widget will usually provide visual feedback when selected.

Pt_SELECT_NOREDRAW

Indicates that the widget won't change its appearance when set or unset. This is meaningful only when the widget is selectable.

Pt_SET

Indicates that the widget is in a "set" state. Generally, this indicates that the widget has been selected.

Pt_TOGGLE

Indicates that pressing the mouse button on this widget will cause it to toggle between being set and unset. Normally, selectable widgets act as push buttons - they become set when you press the mouse button and unset when you release the button.

Pt_WIDGET_REBUILD (read-only)

Indicates that the widget will be rebuilt (re-realized) when the widget engine is finished applying resource changes.

Pt_WIDGET_RESIZE (read-only)

Indicates that the widget will be resized when the widget engine is finished applying resource changes.

The default setting of this resource is 0; that is, no flags have been set.

Pt_ARG_HELP_TOPIC

C type	Pt type	Default
`char *`	String	NULL

The meaning of this resource depends on the Pt_ARG_EFLAGS extended flags:

If Pt_INTERNAL_HELP isn't set, Pt_ARG_HELP_TOPIC is used to set the topic position within the HTML help file.
If Pt_INTERNAL_HELP is set, Pt_ARG_HELP_TOPIC is the help information to be displayed.

For more information, see the PxHelp*() functions and the chapter on Context-Sensitive Help in the Photon Programmer's Guide.

Pt_ARG_POS

C type	Pt type	Default
`PhPoint_t`	Struct	0,0

Defines the x and y values for the widget. This resource isn't displayed in PhAB; PhAB sets it automatically when you move the widget.

Pt_ARG_RESIZE_FLAGS

C type	Pt type	Default
`long`	Flag	0

Controls a widget's resize policy in both the x and y directions. Possible values:

Pt_RESIZE_X_AS_REQUIRED
Pt_RESIZE_X_ALWAYS
Pt_RESIZE_X_INITIAL
Pt_RESIZE_X_BITS
Pt_RESIZE_Y_AS_REQUIRED
Pt_RESIZE_Y_ALWAYS
Pt_RESIZE_Y_INITIAL
Pt_RESIZE_Y_BITS
Pt_RESIZE_XY_ALWAYS
Pt_RESIZE_XY_AS_REQUIRED
Pt_RESIZE_XY_INITIAL
Pt_RESIZE_XY_BITS

Note that each ...BITS flag is a mask that represents all the bits of that type.

The default setting of this resource is 0; that is, no resize policy is in effect.

A widget's resize policy deals solely with the widget's renderable data. For a button, the data is its text; for a container, the data is its children. Any rendered data that doesn't fit within the widget's canvas is clipped.

If no resize policy is in effect, the widget's size is unbounded; it may be made as large or small as specified via Pt_ARG_DIM or Pt_ARG_AREA.

If a resize policy is in effect, the widget will grow or shrink to honor that policy. If the policy is ...ALWAYS, the widget will resize itself to fit its data-the dimensions specified via Pt_ARG_DIM or Pt_ARG_AREA won't apply. If the policy is ...AS_REQUIRED, the widget will resize itself to fit its data only if its current canvas size is inadequate to contain that data. In other words, it will grow, but won't shrink, to fit its data.

If the widget has the ...INITIAL bit set, the resize policy will be applied only once each time the widget is realized. This bit is meaningful only in concert with ...ALWAYS or ...AS_REQUIRED.

Pt_ARG_USER_DATA

C type	Pt type	Default
`void *`	Alloc	NULL

Attaches an arbitrary user-defined data structure to the widget.

Pt_CB_BLOCKED

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of callbacks that the widget invokes whenever it must ignore an event due to being blocked.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_BLOCKED
event: The event that was blocked for this widget.
cbdata: NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_DESTROYED

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

The callbacks that the widget invokes when it is destroyed. You'll find this resource useful for cleaning up variables or memory associated with the widget.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_DESTROYED
event: An event structure filled with NULLs.
cbdata: A value of NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_HOTKEY

C type	Pt type	Default
`PtHotkeyCallback_t *`	Link	NULL

A list of PtHotkeyCallback_t structures. If the widget receives a key event that matches a structure's key cap and key modifiers, the widget will call the function specified in that structure. If a function isn't specified, the widget invokes its Pt_CB_ACTIVATE callback list.

A hotkey isn't invoked if any ancestor of the widget that owns it is blocked.

You can add a Pt_CB_HOTKEY callback to a widget in your application's code by calling PtAddHotkeyHandler(). For more information about this callback, see "Hotkey callbacks" in the Editing Resources and Callbacks in PhAB chapter of the Photon Programmer's Guide.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_HOTKEY

event

A pointer to an PhEvent_t structure.

cbdata

A pointer to a PtHotkeyCallback_t structure that has at least the following members:

unsigned short key_sym_cap;
short flags;
unsigned long key_mods;
PtWidget_t *widget;
void * data;
void * (event_f)( PtWidget_t *,
                void *, PtCallbackInfo_t *);

where:

key_sym_cap

The key cap of the invoking keystroke.

flags

Can contain the following:

Pt_HOTKEY_SYM: Interpret key_sym_cap as a key sym; the default is to interpret it as a key cap.
Pt_HOTKEY_IGNORE_MODS: Ignore the key_mods argument. This flag is typically used in menus, where you want both upper- and lowercase letters to be accepted as hot keys.

key_mods

The key modifiers active for the invoking keystroke.

widget

A pointer to the widget that attached the callback.

data

A pointer to user-defined data associated with the callback, also passed as the second parameter to the callback function.

event_f

If not NULL, a pointer to the function to invoke. If NULL, the widget's Pt_CB_ACTIVATE callback is invoked.

These callbacks should return Pt_CONTINUE.

Pt_CB_RAW

C type	Pt type	Default
`PtRawCallback_t *`	Link	NULL

A list of raw callbacks that the widget invokes if the raw event it receives matches the event mask provided in the PtRawCallback_t structure.

These callbacks are invoked after the widget has processed the event, and then only for events that the widget doesn't consume. Contrast this with the Pt_CB_FILTER resource defined by PtContainer.

You can add a Pt_CB_RAW callback to a widget in your application's code by calling PtAddEventHandler() or PtAddEventHandlers(). For more information about this callback, see "Manipulating event handlers in your code" in the Creating Widgets in Application Code chapter of the Photon Programmer's Guide.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_RAW
event: The raw Photon event that triggered this callback.
cbdata: A value of NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_REALIZED

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of callbacks that the widget invokes whenever it is realized.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_REALIZED
event: An event structure filled with NULLs.
cbdata: A value of NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_UNREALIZED

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of callbacks that the widget invokes whenever it is unrealized.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_UNREALIZED
event: An event structure filled with NULLs.
cbdata: A value of NULL.

These callbacks should return Pt_CONTINUE.

`PtWidget`

Class hierarchy:

PhAB icon:

Public header:

Description:

New resources:

Pt_ARG_AREA

Pt_ARG_BITMAP_CURSOR

Pt_ARG_BORDER_WIDTH

Pt_ARG_CURSOR_COLOR

Pt_ARG_CURSOR_TYPE

Pt_ARG_DATA

Pt_ARG_DIM

Pt_ARG_EFLAGS

Pt_ARG_FLAGS

Pt_ARG_HELP_TOPIC

Pt_ARG_POS

Pt_ARG_RESIZE_FLAGS

Pt_ARG_USER_DATA

Pt_CB_BLOCKED

Pt_CB_DESTROYED

Pt_CB_HOTKEY

Pt_CB_RAW

Pt_CB_REALIZED

Pt_CB_UNREALIZED