X11 Work Bench Toolkit  1.0
ClientMessage Atoms

Variables

Atom aSCROLL_NOTIFY
 
Atom aMENU_COMMAND
 commands sent by menus via ClientMessage More...
 
Atom aMENU_UI_COMMAND
 UI notifications sent by menus to owning Frame windows via ClientMessage using 'WBWindowDispatch'. More...
 
Atom aRESIZE_NOTIFY
 notification of window re-size via ClientMessage More...
 
Atom aDESTROY_NOTIFY
 notify parent that child is being destroyed More...
 
Atom aCONTROL_NOTIFY
 dialog control and child window notification messages More...
 
Atom aQUERY_CLOSE
 query if it's ok to close (and optionally destroy yourself if ok) a window More...
 
Atom aRECALC_LAYOUT
 notify window that it should re-calculate things like scrollbars and viewports More...
 
Atom aDLG_FOCUS
 dialog focus messages More...
 
Atom aSET_FOCUS
 dialog focus messages More...
 
Atom aWM_CHAR
 keystroke/character notifications generated by API More...
 
Atom aWM_TIMER
 timer notifications generated by API More...
 
Atom aWM_POINTER
 pointer click/double-click/drag notifications generated by API More...
 

Detailed Description

Atoms used for XClientMessageEvent notifications
Includes details on the various message parameters

Variable Documentation

Atom aCONTROL_NOTIFY

dialog control and child window notification messages

CONTROL_NOTIFY message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aCONTROL_NOTIFY
format == 32 (always)
data.l[0] contains the dialog control ID (or -1 if N/A)
data.l[1] is the notify code
data.l[2] is window ID

Definition at line 246 of file window_helper.c.

Atom aDESTROY_NOTIFY

notify parent that child is being destroyed

RESERVED - not yet implemented TODO document DESTROY_NOTIFY format here

Definition at line 232 of file window_helper.c.

Atom aDLG_FOCUS

dialog focus messages

DLG_FOCUS message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aDLG_FOCUS
format == 32 (always)
data.l[0] is a tri-state value as follows

  • less than zero for 'previous window'
  • greater than zero for 'next window'
  • equal to zero for 'set to this window'

data.l[1] is the control id to set focus to (for data.l[0] == 0)

Definition at line 308 of file window_helper.c.

Atom aMENU_COMMAND

commands sent by menus via ClientMessage

MENU_COMMAND message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aMENU_COMMAND
format == 32 (always)
data.l[0] Menu command message ID (aka 'action')
data.l[1] (truncated) pointer to the WBMenu object (cast to 'long', truncated to 32 bits)
data.l[2] Window ID of the menu bar

Definition at line 167 of file window_helper.c.

Atom aMENU_UI_COMMAND

UI notifications sent by menus to owning Frame windows via ClientMessage using 'WBWindowDispatch'.

MENU_COMMAND message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aMENU_UI_COMMAND
format == 32 (always)
data.l[0] Menu command message ID (aka 'action')
data.l[1] low 32-bits of WBMenu object pointer
data.l[2] high 32-bits of WBMenu object pointer
data.l[3] low 32-bits of WBMenuItem object pointer
data.l[4] high 32-bits of WBMenuItem object pointer

A Frame Window returns '0' to indicate that the menu should be displayed normally (same as 'not handled')
Other return values alter the display of the menu.

For a popup menu: -1 : disables the menu 1 : enables the menu (default behavior if no UI handler present, but menu handler IS present) 0 : menu item NOT handled (menu item will be greyed)

For a dynamic menu: (preliminary) - popup menu items only (not found in top-level menus) -1 : disabled the menu 0 : 'not handled' or 'error' (no dynamic menu will be added or displayed) >0 : a 'secure internal pointer hash' representing an actual pointer value (preliminary, RESERVED) this pointer will be to a WBAlloc'd block of memory describing the menu items (as text). It will be necessary for the caller to interpret this text to create the dynamic memory items. PRELIMINARY: the text will be 'menu text\tAtom Name' - no hotkeys, no tooltip text. The menu text can include underscores which will only work when the popup is available

TODO: change this to be 'less dangerous' with respect to getting invalid pointers jammed into the queue. It is theoretically possible for a different application to post Client Message events using faked values.

Definition at line 204 of file window_helper.c.

Atom aQUERY_CLOSE

query if it's ok to close (and optionally destroy yourself if ok) a window

CONTROL_NOTIFY message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aQUERY_CLOSE
format == 32 (always)
data.l[0] contains a non-zero value if the window should destroy its private data NOW; 0 otherwise

Window callbacks should check for this and return '0' when it's ok to destroy the window, a positive value if it's NOT ok, or a negative value on error.

Whenever data.l[0] contains a non-zero value, and it's ok to close the window, the window event handler should destroy all of its private data, zero out data element '0' for the window data (if it pointed to the private data), and call WBUnregisterWindowCallback() for itself. The window will be destroyed by the sender as soon as the callback returns.

If the callback returns a non-zero value, it should not destroy any of its own private data. The sender will assume that it's not ok to close the window and will try to leave everything 'as-is'.

Generally, you should return 0 if ok to close the window, 1 if NOT ok to close, and '-1' on error.

Definition at line 272 of file window_helper.c.

Atom aRECALC_LAYOUT

notify window that it should re-calculate things like scrollbars and viewports

CONTROL_NOTIFY message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aRECALC_LAYOUT
format == 32 (always)

A window that has a viewport and scrollbars, using a text object or other construct that supports this ClientMessage atom, should check for this message and recalculate viewports and scrollbar positions whenever it is received. If scroll positions have changed, you should invalidate the entire window rectangle so that it can be re-painted. However, you should not paint the window synchronously. You should rely on asynchronous processing of Expose events.

Definition at line 290 of file window_helper.c.

Atom aRESIZE_NOTIFY

notification of window re-size via ClientMessage

RESIZE_NOTIFY message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aRESIZE_NOTIFY
format == 32 (always)
data.l[0] new 'left' client rectangle coordinate
data.l[1] new 'top' client rectangle coordinate
data.l[2] new 'right' client rectangle coordinate
data.l[3] new 'bottom' client rectangle coordinate

The return value is ignored. It is typically sent via a direct call to the message callback function. Since it is merely a notification message, it does not need to be handled. The specified coordinates are in 'client' coordinates relative to the upper left corner of the client area, which is always (0,0).

Definition at line 223 of file window_helper.c.

Atom aSCROLL_NOTIFY

Scroll notifications via ClientMessage

MENU_COMMAND message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aSCROLL_NOTIFY
format == 32 (always)
data.l[0] Identifies the bar (SCROLL_VERTICAL, SCROLL_HORIZONTAL, or SCROLL_DEFAULT)
data.l[1] Indicates the notification type, one of the following:

  • WB_SCROLL_KNOB 'knob track' - knob position will be in data.l[2]
  • WB_SCROLL_FORWARD move down, or move right
  • WB_SCROLL_BACKWARD move up, or move left
  • WB_SCROLL_PAGEFWD page down or page right
  • WB_SCROLL_PAGEBACK page up or page left
  • WB_SCROLL_FIRST scroll to first entry, i.e. home or top
  • WB_SCROLL_LAST scroll to last entry, i.e. bottom or end
  • WB_SCROLL_DBLCLICK double-click detection (no selection info in data.l[2])
  • WB_SCROLL_ABSOLUTE absolute scroll, to the absolute position in data.l[2]
  • WB_SCROLL_RELATIVE relative scroll, relative +/- position in data.l[2]
  • WB_SCROLL_NA generic 'NA' or 'UNDEFINED' value

data.l[2] Optional parameter, typically the absolute or relative scroll position

Definition at line 203 of file dialog_support.c.

Atom aSET_FOCUS

dialog focus messages

SET_FOCUS message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aSET_FOCUS
format == 32 (always)
data.l[0] is the window ID to set focus to (None for default)

This message is typically sent to the application (.window = None)

By posting a SET_FOCUS message to the application, you can ASYNCHRONOUSLY fix focus-related problems, such as the window manager trying to set focus to the application window while a modal dialog is visible.
When sent to a frame window, you are requesting that it set the focus to the appropriate window, similar to aDLG_FOCUS
Assigning 'data.l[0]' to 'None' tells a frame window to set focus to the default. When sent to the application, a value of 'None' is meaningless.

Definition at line 330 of file window_helper.c.

Atom aWM_CHAR

keystroke/character notifications generated by API

Mid-level keystroke handling generates WM_CHAR notifications via ClientMessage passed to the appropriate window in addition to normal key up/down events.

WM_CHAR notification message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aWM_CHAR
format == 32 (always)
data.l[0] is return frmo WBKeyEventProcessKey
data.l[1] is *piAltCtrlShift from WBKeyEventProcessKey
data.l[2] is # of characters decoded into data.l[3..4]
data.l[3..4] (as char[]) is decode buffer (at least 8 chars long, possibly 16 for 64-bit)

see also: WBKeyEventProcessKey()character notifications (generated by API; avoids key up/down handling)

Definition at line 350 of file window_helper.c.

Atom aWM_POINTER

pointer click/double-click/drag notifications generated by API

Mid-level pointer click/double-click/drag handling generates WM_POINTER notifications (i.e. mouse motion) via ClientMessage passed to the appropriate window in addition to the normal pointer notification events via the normal event system.

WM_POINTER notification message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aWM_POINTER
format == 32 (always)
data.l[0] is one of the notification codes

data.l[1] is a bitmap of the mouse button state (bit set when pressed)

  • WB_POINTER_BUTTON1 - bit 0 - left button
  • WB_POINTER_BUTTON2 - bit 1 - right button
  • WB_POINTER_BUTTON3 - bit 2 - center button
  • WB_POINTER_BUTTON4 - bit 3 - mouse wheel up
  • WB_POINTER_BUTTON5 - bit 4 - mouse wheel down

data.l[2] is 'WB_KEYEVENT_xxx' mask for CTRL+ALT+SHIFT

  • WB_KEYEVENT_ALT
  • WB_KEYEVENT_CTRL
  • WB_KEYEVENT_SHIFT

data.l[3] is translated X coordinate
data.l[4] is translated Y coordinate
'pointer' notifications (generated by API)

Definition at line 406 of file window_helper.c.

Atom aWM_TIMER

timer notifications generated by API

Mid-level timer handling generates WM_TIMER notifications via ClientMessage passed to the appropriate window, either periodic or 'one-shot'
See CreateTimer() for more information.

WM_TIMER message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aWM_TIMER
format == 32 (always)
data.l[0] is the unique identifier associated with the timertimer notifications (generated by API)

Definition at line 366 of file window_helper.c.