X11 Work Bench Toolkit  1.0
ClientMessage Atoms

Enumerations

enum  {
  WB_SCROLL_DEFAULT = 0, WB_SCROLL_HORIZONTAL = 1, WB_SCROLL_VERTICAL = 2, WB_SCROLL_KNOB = 0,
  WB_SCROLL_FORWARD = 1, WB_SCROLL_BACKWARD = -1, WB_SCROLL_PAGEFWD = 2, WB_SCROLL_PAGEBACK = -2,
  WB_SCROLL_FIRST = -3, WB_SCROLL_LAST = 3, WB_SCROLL_DBLCLICK = 4, WB_SCROLL_ABSOLUTE = 99,
  WB_SCROLL_RELATIVE = -99, WB_SCROLL_NA = 0x80000000
}
 Enumeration for aSCROLL_NOTIFY ClientMessage. More...
 

Variables

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 aSCROLLBAR_NOTIFY
 notification of window scrollbar position/range changes 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 aSCROLL_NOTIFY
 
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

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumeration for aSCROLL_NOTIFY ClientMessage.

Enumeration of values used in scroll notification messages.

See also
WBScrollBarEvent()
Enumerator
WB_SCROLL_DEFAULT 

1st parameter (bar) - 'Default Bar', currently not implemented, probably won't be used

WB_SCROLL_HORIZONTAL 

1st parameter (bar) - The horizontal scroll bar for the control or window

WB_SCROLL_VERTICAL 

1st parameter (bar) - The vertical scroll bar for the control or window.

WB_SCROLL_KNOB 

2nd parameter (direction) - 'knob track' - pos in data.l[2]

WB_SCROLL_FORWARD 

2nd parameter (direction) - down, right

WB_SCROLL_BACKWARD 

2nd parameter (direction) - up, left

WB_SCROLL_PAGEFWD 

2nd parameter (direction) - pgdn, pgright

WB_SCROLL_PAGEBACK 

2nd parameter (direction) - pgup, pgleft

WB_SCROLL_FIRST 

2nd parameter (direction) - home, top

WB_SCROLL_LAST 

2nd parameter (direction) - bottom, end

WB_SCROLL_DBLCLICK 

2nd parameter (direction) - double-clicked item (no selection change info) (sent to list control's owner)

WB_SCROLL_ABSOLUTE 

2nd parameter (direction) - absolute scroll - pos in data.l[2]

WB_SCROLL_RELATIVE 

2nd parameter (direction) - relative scroll - rel pos in data.l[2]

WB_SCROLL_NA 

generic 'NA' or 'UNDEFINED' value

Definition at line 694 of file window_helper.h.

Variable Documentation

◆ aCONTROL_NOTIFY

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 262 of file window_helper.c.

◆ aDESTROY_NOTIFY

Atom aDESTROY_NOTIFY

notify parent that child is being destroyed

RESERVED - not yet implemented TODO document DESTROY_NOTIFY format here

Definition at line 248 of file window_helper.c.

◆ aDLG_FOCUS

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 355 of file window_helper.c.

◆ aMENU_COMMAND

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] secure hash for WBMenu object pointer - see WBCreatePointerHash()
data.l[2] Window ID of the menu bar
Whenever this message is received, you should NOT call WBDestroyPointerHash() for the WBMenu object pointer. This will be done automatically by the message framework.

Definition at line 166 of file window_helper.c.

◆ aMENU_UI_COMMAND

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] secure hash for WBMenu object pointer - see WBCreatePointerHash()
data.l[2] secure hash for WBMenuItem object pointer - see WBCreatePointerHash()
data.l[3] the value '0' (reserved)
data.l[4] the value '0' (reserved)
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

Whenever this message is received, you should NOT call WBDestroyPointerHash() for the WBMenu object pointer, nor for the WBMenuItem object pointer. This will be done automatically by the message framework.

Definition at line 203 of file window_helper.c.

◆ aQUERY_CLOSE

Atom aQUERY_CLOSE

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

QUERY_CLOSE 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 314 of file window_helper.c.

◆ aRECALC_LAYOUT

Atom aRECALC_LAYOUT

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

RECALC_LAYOUT 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.

In some cases, default handling of 'recalc layout' functionality may cause aSCROLLBAR_NOTIFY and/or aRESIZE_NOTIFY client message events to be dispatched. Care should be taken to NOT cause an infinite loop or infinite recursion due to the handling of these events.

See also
aSCROLLBAR_NOTIFY, aRESIZE_NOTIFY

Definition at line 337 of file window_helper.c.

◆ aRESIZE_NOTIFY

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 222 of file window_helper.c.

◆ aSCROLL_NOTIFY

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 288 of file window_helper.c.

◆ aSCROLLBAR_NOTIFY

Atom aSCROLLBAR_NOTIFY

notification of window scrollbar position/range changes via ClientMessage

SCROLLBAR_NOTIFY message format (relative to XEvent.xclient)
type == ClientMessage
message_type == aSCROLLBAR_NOTIFY
format == 32 (always)
(data is reserved)

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 message callback should check its own cached scroll information against the sender's (typically a child frame) and make any necessary changes for consistency, then (as needed) invalidate and asynchronously re-paint itself

Definition at line 239 of file window_helper.c.

◆ aSET_FOCUS

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 377 of file window_helper.c.

◆ aWM_CHAR

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 from 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 397 of file window_helper.c.

◆ aWM_POINTER

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 455 of file window_helper.c.

◆ aWM_TIMER

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 timer

see also: CreateTimer(), DeleteTimer()timer notifications (generated by API)

Definition at line 415 of file window_helper.c.