3. Primitives

Here is introduction to XWEM primitives, such as Frame, Window, Client, minibuffer, specials, etc.

3.1 Frame

Frame is general thing that used to hold XWEM windows(see section 3.2 Window). Usually Frame have something like titlebar which is used to display information related to manager state, such as names for XWEM Clients(see section 3.3 Client) or user defined information.

TODO: add some info about Frames properties, such as GCs list, root window, selected window, etc.

Function: xwem-frame-p frame

Returns non-nil if frame is XWEM Frame.

3.1.1 Basic Frames

TODO: write me

3.1.2 Creating Frames

Here is describe functions which is used to create frames. Also describe default bindings to create frames. Describe side by side splits.

TODO: write me

3.1.3 Frame Properties

Each XWEM Frame have properties list, which is altered when creating Frame.

Here should be description of Frame's properties, default values, etc.

TODO: write me

3.1.4 Frame Title

Description of Frame tabber.

TODO: write me

3.1.5 Deleting Frames

You may easily delete any of XWEM Frame. All clients that have Frame as parent window will be reparented to root window.

Here is should be description for default keybindings for frame deletion and functions description.

TODO: write me

3.1.6 Frames Operations

Here is description about what you can do with Frame. Switching, linkage switching, etc.

TODO: write me

3.1.7 Embedded Frames

Embedded Frame is Frame and CL at the same time.

Here is description on how to create embedded frames, how to unembed them and so on.

TODO: write me

3.1.8 Frames variables and functions

Variable: xwem-frame-background

This is symbol specifies background color used in XWEM Frame. This color should be in xwem-gc-syscolors or in xwem-gc-bonus-colors.

xwem-frame-backgroud => "gray60"

Variable: xwem-frame-cursor-shape

This specifies shape of cursor when pointer is over XWEM Frame. It is value of one of X-XC-... variable.

(eq xwem-frame-cursor-shape 'X-XC-left_ptr) => t

Variable: xwem-frame-cursor-foreground-color

Specifies cursor's foreground color when pointer is over XWEM Frame.

xwem-frame-cursor-foreground-color => "#002800"

Variable: xwem-frame-cursor-background-color

Cursor's background color when pointer over XWEM Frame.

Variable: xwem-frame-defprops

Plist which is used to define default properties for newly created XWEM Frames. Keys in this plist is symbols, you can use one of:

title-height - Height in pixels to be used for title bar.

inner-border-width - Width in pixels of XWEM Frame's inner border.

otter-border-width - Width in pixels of XWEM Frame's otter border.

title-thickness - Used for 3D view of title bar.

xwem-frame-defprops => (inner-border-width 0 otter-border-width 0 title-height 17 title-thickness 2)

Variable: xwem-face-frame-selected-win-selected

Face used to outline selected Window in selected Frame.

Variable: xwem-face-frame-selected-win-nonselected

Face used to outline non-selected Window in selected Frame.

Variable: xwem-face-frame-nonselected-win-selected

Face to outline selected Window in non-selected Frame.

Variable: xwem-face-frame-nonselected-win-nonselected

Face to outline non-selected Window in non-selected Frame.

Variable: xwem-face-win-delimeter

Face to draw Window delimeter.

Variable: xwem-face-win-delimeter-shadow

Face to draw shadow of Window delimeter.

Variable: xwem-frame-rolling-switch

Non-nil mean that xwem-frame-next and xwem-frame-previous commands will always switch, even if there no next or previous Frame.

Variable: xwem-frame-switch-hook

Hooks to be called when Frame switching occurs (i.e. xwem-current-frame changes). Function will receive two arguments old-frame and new-frame.

Variable: xwem-frame-keymap

Keymap used in Frames.

Variable: xwem-frames-list

List of all Frames.

Variable: xwem-current-frame

Refers to currently selected Frame.

Function: xwem-frame-p frame

Return non-nil if frame is valid XWEM Frame.

(xwem-frame-p t) => nil

Function: xwem-frame-alive-p frame

Return non-nil if frame is alive frame, i.e. in xwem-frames-list.

Function: xwem-frame-mapped-p frame

Return non-nil if frame is mapped, i.e. its contents shown.

Function: xwem-frame-map frame

Map frame, i.e show it contents.

Function: xwem-frame-selected

Return currently selected Frame.

Function: xwem-frame-selected-p frame

Return non-nil if frame is selected Frame.

Function: xwem-frame-select frame &optional dnr-hooks

Make frame to be selected. Runs xwem-frame-switch-hooks if frame is not already selected and dnr-hooks non-nil.

Function: xwem-frame-select-defhook old-frame new-frame

Default hook that present in xwem-frame-switch-hooks.

TODO: describe other functions ..

Function: xwem-init-frames

Initialise all stuff needed to manipulate with XWEM Frames.

Function: xwem-make-frame props

Creates new Frame with merged xwem-frame-defprops and props together properties.

Function: xwem-find-frame xwin

Find Frame by X Window xwin

Function: xwem-frame-find how arg

Find Frame according to how and arg. how can be one of xwin, win or cl. arg is X Window, XWEM Window or XWEM Client respectively.

Function: xwem-frame-num frame

Return index position of frame in xwem-frame-list.

Function: xwem-frame-draw frame fully

Draw frame. If fully is non-nil then XClearArea Frame's X window before drawing.

Function: xwem-frame-redraw frame

Outlines Windows inside frame.

Function: xwem-frame-switch-nth n

Switch to n XWEM Frame in xwem-frame-list.

Function: xwem-frame-del-win &optional frame window

Removes XWEM window from XWEM frame.

Function: xwem-frame-del-others &optional frame window

Removes all XWEM Windows from XWEM frame other then window.

Function: xwem-frame-split-horiz &optional frame

Splits XWEM frame horizontally.

Function: xwem-frame-split-vert &optional frame

Splits XWEM frame vertically.

Function: xwem-frame-win-enlarge-hor n

Enlarges xwem-win-selected in xwem-frame-selected by n pixels horizontally.

Function: xwem-frame-win-enlarge-ver n

Enlarges xwem-win-selected in xwem-frame-selected by n pixels vertically.

Function: xwem-frame-goto direction &optional frame

Go to next XWEM Window in frame in direction.

3.2 Window

In this chapter we will discuss thing related to XWEM's Windows.

3.2.1 Basic Windows

Window is subpart of Frame(see section 3.1 Frame) that holds Clients (see section 3.3 Client). Each Frame always contain at least one Window, but you con divide it vertically or horizontally to obtain new Windows. Windows never overlaps. There is always selected Window in each Frame, but it is not guaranties that Client in selected Window will have input focus.

Function: xwem-init-win

Initilizes all stuff we will need.

Variable: xwem-win-default-properties

Plist of default properties for newly created Windows. Keys in list is one of symbol:

• dead Window referenced but not workable.
• deleted Deleted Windows have this non-nil.
• frame Reference to XWEM Frame.
• next Next window in windows double linked list.
• prev Previous window in windows double linked list.
• hchild Horizontal child.
• vchild Vertical child.
• client Link to XWEM Client that is in XWEM Window or nil.
• expectances Expectances plist for XWEM Window.

Function: xwem-win-p win

Return non-nil if win is Window.

3.2.2 Splitting Windows

Functions described here is used in way to split XWEM's window or get information about split.

Variable: xwem-win-min-width

Minimal width in pixels that XWEM Window may have after spliting.

xwem-win-min-width => 40

Variable: xwem-win-min-height

Minimal height in pixels that XWEM Window may have after spliting.

xwem-win-min-height => 40

Function: xwem-win-split &optional window how new-size

Splits XWEM window, how is one of vertical or horizontal(default is horizontal). new-size is size in pixels which should have window after split.

Function: xwem-win-only-one-p &optional window

Returns non-nil if window is only one in XWEM Windows chain.

3.2.3 Deleting Windows

Function: xwem-window-delete &optional window

Deletes XWEM window. If ommited than xwem-win-selected will be used.

Function: xwem-window-delete-others &optional window

Deletes all XWEM Windows other then window.

Function: xwem-win-delete-subwindows window

Mark all child of XWEM window as deleted.

Function: xwem-win-mark-deleted window

3.2.4 Selecting Windows

Select a window means that client currently in than window receives input focus.

Variable: xwem-win-switch-hook

Hooks that will be runned when selected window changes. Functions in should accept two arguments - old-win and new-win.

xwem-win-switch-hook => (xwem-win-focus xwem-win-title)

Function: xwem-win-selected

Returns selected XWEM Window.

Function: xwem-win-selected-p window

Return non-nil if window is selected.

Function: xwem-window-select window

Select window as current XWEM Window. Runs xwem-win-switch-hooks.

3.2.5 Cycling Windows

Function: xwem-win-make-list-by-next window

Creates list of XWEM Windows using next property.

Function: xwem-win-new props

Creates new XWEM Window using properties obtained after merging xwem-window-defprops and props together.

Function: xwem-win-replace oldw neww

Replace oldw XWEM Window with contents of neww XWEM Window.

Function: xwem-win-make-parent window

Creates dummy parent XWEM Window for window.

Function: xwem-window-next &optional window

Returns next XWEM Window after window in canonical ordering.

Function: xwem-window-next-vertical &optional window

Returns XWEM Window which is vertically after window.

Function: xwem-window-prev &optional window

Returns previous XWEM Window before window in canonical ordering of XWEM Windows.

Function: xwem-win-map fn &optional window

Apply fn function to window and each child of it. fn will be called with an XWEM Window as argument.

Function: xwem-win-count &optional window

Count childs in window.

Function: xwem-window-list &optional frame

nil

Here is somelike windmove package.

Function: xwem-winmove-left &optional arg

Move to the left. TODO: describe arg.

Function: xwem-winmove-right &optional arg

Move to the right. TODO: describe arg.

Function: xwem-winmove-up &optional arg

Move to the up. TODO: describe arg.

Function: xwem-winmove-down &optional arg

Move to the down. TODO: describe arg.

TODO: write me

3.2.6 Resizing Windows

Here functions that operations on window's sizes.

Function: xwem-window-set-pixsize window nsize nodelete is-height

Sets size of window to nsize in pixels. If is-height is non-nil then nsize is new window height.

Function: xwem-window-change-size window delta height-p

Changes XWEM window size to old-size plus delta. height-p is non-nil if height changes.

TODO: add shrink and enlarge

3.2.7 Window Configurations

Function: xwem-window-configuration &optional frame

Return current Windows configuration for frame. You can restore it than using xwem-set-window-configuration.

Function: xwem-set-window-configuration win-config

Restore window configuration win-config, returned by xwem-window-configuration.

3.2.8 Drawing Windows

Variable: xwem-win-delim-width

XWEM Window delimeter width in pixels, including shadow.

Variable: xwem-win-delim-shadow-thicksness

When drawing 3D shadows for XWEM Window delimeters, this variable used.

Function: xwem-win-draw-delims window

Draws delimeters in XWEM window.

3.2.9 Window Expectances

Expectances is thing describes which clients cirtain XWEM Window wait to manage.

TODO: write me

3.3 Client

Client is normal X11 application already managed by XWEM. All XWEM Clients manages according to XWEM Manage Database(see section 4.4 Manage Database). Default behaviour is to enlarge each XWEM Client which have no override redirect flag ot XWEM Window used to hold that Client.

3.3.1 Client Basics

TODO: describe what is XWEM Client.

Function: xwem-cl-p client

Returns non-nil if client is Client.

3.3.2 Client Properties

Each Client in XWEM have some properties associated with it.

Function: xwem-client-name cl &optional clist

Return unique name for Client cl using clist as list of Clients.

3.3.3 Current Client

Current Client is client in selected Window.

TODO: describe things related to special XEmacs frames.

Function: xwem-cl-selected

Return selected Client.

3.3.4 Clients Lists

TODO: describe client lists.

Variable: xwem-clients

List of all Clients.

3.3.5 Client Hooks

TODO: genaral overview of hooks used in Client processing.

Variable: xwem-cl-setup-hooks

List of hooks which is called after XWEM Client is managed. Functions in that list should accept one argument - XWEM Client.

Variable: xwem-cl-manage-hook

Functions to call when Client managed. They are passed with one argument - cl.

Variable: xwem-cl-demanage-hook

Functions to call when Cliend demanages. Called with with one argument - cl.

3.3.6 Operating on Clients

Here is some usefull functions you can use to operate on Clients.

Function: xwem-find-client xwin-or-id

Find Client by X window xwin-or-id.

Function: xwem-remove-client cl

Remove cl from Clients list xwem-clients.

TODO: write me

3.4 XWEM Minibuffer

XWEM minibuffer is global minibuffer(usually value of default-minibuffer-frame) used as minibuffer by all XEmacs frames.

TODO: write me

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.