|
Allegro CL version 11.0 | ||||||||
Generic Function, cg package
Arguments: widget
Returns the 3d border width of widget.
Generic Function, cg package
Arguments: group-box
Returns or sets (with setf) the 3d style width of group-box. See the description of the group-box control.
Function, cg package
Arguments:
Returns true if a Microsoft "Visual Style" is currently in effect; returns nil otherwise. The value will always be nil on platforms other than Microsoft Windows.
A Visual Style is in effect on Windows if there is a "manifest file" and the user has not selected "Windows Classic" in Control Panel | Display | Themes. See ide:include-manifest-file-for-visual-styles for more information.
Generic Function, cg package
Arguments: window menu
Called whenever a menu is about to be made visible. window is the owning window. menu is the menu about to be displayed.
The default method calls about-to-show-menu recursively on the selected child of window. An application may add methods to this generic function in order to modify a menu that is about to be shown, making it suitable for the current context. This is most useful for pull-down menus, since they are not invoked by application code that could otherwise modify the menu before invoking it. You might, for example, want to make certain menu-items unavailable when the menu is displayed because the items are not meaningful in the current environment. The menu command Cut should typically be unavailable when nothing is selected, for example.
See cg-events.htm for information about event handling in Common Graphics. See also the menu chapter in the IDE User Guide, which has examples using this function.
Generic Function, cg package
Arguments: outline-item
Returns whether an outline-item will be drawn above its parent item rather than in the normal location below the parent. The value may be set at creation time by passing the above-parent initarg, or any time later by calling (setf above-parent). The default value is nil.
Placing some outline-items above their parent and others below could be used to distinguish the two groups of items in some application-specific way.
An outline-item will be placed above its parent item only when its above-parent property is true and the outline widget's handle-above-parent property is also true.
Generic Function, cg package
Arguments: timer
A boolean value indicating whether a timer is currently running. An active timer fires each time its interval passes, while an inactive timer does nothing. This property of a timer will be true if start-timer has been called on the timer more recently than stop-timer has. If the active property is explicitly modified by an application from nil to true, then start-timer is called internally, and if the active property is explicitly modified from true to nil, then stop-timer is called internally. Therefore, in order to wrap all starting and stopping of timers, it is sufficient to add start-timer and stop-timer methods.
active is a property of the timer class.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: window &optional (key (name window)) (subkey (default-application-window-subkey)) always
Caches a window so that it can later be retrieved by find-application-window using the specified key (which defaults to the name of the window being cached)) and the specified subkey (which defaults to the value returned by default-application-window-subkey).
Typically you would accept the default values for key and subkey, and later pass only the name of the window to find-application-window. But these arguments could be any two values at all, as long as you pass values that are eq to them to find-application-window to find this window.
If always is true, then the specified window will replace any existing window that has the same key and subkey in the cache of all application windows. If always is nil, then the specified window is not added to the cache of all application windows if there is already a window there that has the same key and subkey. The default is nil.
See also remove-application-window.
Generic Function, cg package
Arguments: outline &key value
Creates an outline-item that has the specified value, and adds it to the specified outline as a child of the currently selected item, if any, and otherwise as a top-level item. The item will be positioned at the top of its siblings.
This function is a specialization of the more general function add-outline-item-value, and could be used directly for an interactive command to create a child of the selected item.
Function, cg package
Arguments: class-grid data-object &key *index scroll-into-view focus-on-row
Adds a single object to the list of objects that a class-grid is displaying. An alternative is to replace the whole set of displayed objects by calling (setf value) on the grid, passing a list of all objects to display.
Internally this creates a class-grid-body-row and adds it to the body row-section of the grid-widget.
class-grid is the class-grid to which an object will be added.
data-object is the new object to display. It should be an instance of the edited-class of the class-grid.
index specifies the position of the new grid-row among the existing rows. It may be either an integer index, where zero means to add the row at the very top, or else nil to add the row at the very bottom. The default is nil.
If scroll-into-view is true, then the body row-section will be scrolled as needed to make the new row fully visible. If nil, then this is not done. The default is nil.
If focus-on-row is true, then the keyboard focus within the grid will be moved to a cell of the new row. If nil, then this is not done. The default is nil. A true value still does not move the keyboard focus to the class-grid itself, but when it is next moved there the focus will be in the new row. An application could call set-focus-component to move the focus to the class-grid to allow the user to immediately edit the new row.
Modifying the list of instances that a class-grid displays will call the grid's on-change function because the list of instances is stored as the value property of the widget.
See also delete-class-grid-row.
Generic Function, cg package
Arguments: list-view-or-grid-column-section list-view-column-or-grid-column &optional index
For a list-view control, adds a new list-view-column specified by list-view-column-or-grid-column to list-view-or-grid-column-section at index. An index of zero indicates the leftmost position, 1 means second from the left, and so on. An index of -1 (this is the default for list-views) means in the rightmost position. See the description of the list-view control.
For a grid-widget control, adds a grid-column, specified by the list-view-column-or-grid-column to the grid-column-section specified by list-view-or-grid-column-section at the specified index among the columns of that section. An index of zero indicates the first (leftmost) position. A huge number can be used for index to add to the end. The default index for the grid-widget method is zero. Alternately, (setf subsections) can be called to replace the entire set of columns of the column section.
Generic Function, cg package
Arguments: window &rest options &key (font (status-bar-font window)) parts min-height (minimum-height min-height) size-grip-p along-top-p name
Creates a status-bar that has multiple sections, rather than allowing multiple lines of text as with status-bars created by add-status-bar. The status bar is placed along the bottom of window. Panes that are siblings of the new status-bar and overlap with it are automatically resized so they no longer overlap with the new status-bar. The status bar added by this function has a more Windows look and feel compared to that added by add-status-bar but, as mentioned, supports only one line of text.
The arguments are:
font specifies the font that will be used for status-bar messages. The height of the status-bar is set to fit this font.
parts can be a list of section widths (a number or t) into which the status-bar will be divided. If some members of the list are t, then those sections will be assigned a width such that they are equally wide and just wide enough to make all of the sections cover the entire width of window.
min-height can be used to make the status-bar taller than its default, which is the height of the status-bar's font.
size-grip-p is designed to control whether a resizing icon is added at the right end of the status-bar (yes if true, no if nil) but the OS seems to add it in all cases.
along-top-p if true adds the status-bar to the top of window rather than the bottom as usual. The automatic resizing of sibling panes to make room for the status-bar is not implemented when the status-bar is placed along the top.
name, if supplied, should be a symbol (we recommend using a keyword) providing a programmatic handle for the status bar, suitable as the name argument to, e.g., find-named-object.
Note that the argument list of this function as returned by arglist (or describe or other tools) includes &rest options. This is included for internal technical reasons. From the programmer's point of view, there is one required argument and a number of keyword arguments.
Generic Function, cg package
Arguments: widget dialog &optional behind hidden
Adds the control specified by the widget argument to the dialog-window dialog.
The keyword arguments are:
behind: if specified t, the new control will be placed behind the other sibling widgets in the occlusion stack. If nil (the default), the new control will be in front of the others and be first in the tab order. A value other than t or nil must be a sibling widget on dialog. The new widget will be placed behind that one in the occlusion stack.
When creating many widgets by calling add-component for each one, it may be more efficient to pass behind as t for each one, because the operating system creates child windows in back initially, and also there will be no movement of the keyboard focus to each new widget as it is created as there is when each one is added in front (if the parent window has already been expanded). (When creating the widgets instead by passing a list of the widgets as the :dialog-items initarg to make-window, they are added to the parent window in front-to-back order internally.)
hidden: If specified true, the new control will be added to the dialog but its window will not appear until the program later expands it explicitly. If nil (the default), the new control will appear with the dialog.
widget is returned.
Generic Function, cg package
Arguments: tab-control tab-id widget
Adds widget to tab-control on the tab whose programmatic name (id) is tab-id. (A tab on a tab-control is an instance of a tab-info object. Applying name to a tab-info results in a suitable value for the tab-id argument.) Note that the control specified by widget is not moved so that it is over the tab-control, but it will be exposed when the tab it is on is selected and hidden when another tab is selected.
See the description of the tab-control class/control.
Function, cg package
Arguments: event-synonym function-name
This function establishes a global keyboard shortcut that does not have a corresponding menu-item on a top-level menubar.
event-synonym should be a character or a list of modifier keys and a character, to denote a keyboard event that should run some function globally. This argument can be a key-chord that will invoke the command. An event-synonym always contains a single main non-shift key, plus an optional set of one or more shift keys.
If no shift keys are used, then the event-synonym consists entirely of a character name like #\A or a key name like vk-comma or vk-f3.
If shift keys are used, then the event-synonym is a list whose members are the names of the shift keys (in any order) and the main non-SHIFT key as the last member. The available shift key names are control-key, alt-key, and shift-key, and they may be used in any combination.
Normally, typable characters (such as letters and numbers) are used only in combination with either control-key or alt-key (or both), since otherwise you could not input the characters as text.
function-name denotes the function to run. The function should take one argument, which will be the top-level window of the window that had the keyboard focus when the specified keys were pressed. The function should return true to disable any further processing of this event, or nil to allow the keyboard event to still be looked up in the top-level window's menu bar or to be otherwise handled by the selected window's event handler.
A global keyboard accelerator will take precedence over any other handling of its keypress event in any window, including windows that have comtabs. (In the IDE, the editor and Debug Window have comtabs. See comtab.)
The function for a global keyboard accelerator will run in the thread that created the window that had the keyboard focus when the keypress event occurred. For standard IDE windows, this will be the IDE GUI thread. If it is desirable to run the code in a Listener thread instead, where user evaluations are normally done, the function eval-in-listener-thread could be used in the accelerator's function to do so.
Global keyboard accelerators can be removed with remove-global-keyboard-accelerator.
Examples
Here are two examples that define global accelerators that move the selected window by 8 pixels either up or down. The first example (to move the window up) illustrates calling a separately defined function and using one of the vk-foo names for keys that don't have printable characters on them, and the second example (to move the window down) illustrates using an in-place function object and using the character that's printed on the lower (unshifted) part of the key.
;; Define a function to move a window upward by eight pixels.
(defun move-up (window)
(with-positions (pos1)
(move-window-relative window (nmake-position pos1 0 -8)))
t)
;; Make alt-backspace move the current window up.
(add-global-keyboard-accelerator
'(alt-key vk-backspace) 'move-up)
;; Define a lambda function to move a window downward by eight pixels
;; and make control-shift-8 invoke it.
(add-global-keyboard-accelerator
'(control-key shift-key #\8)
#'(lambda (window)
(with-positions (pos1)
(move-window-relative window (nmake-position pos1 0 8)))
t))
;; Return true to override any other control-shift-8 handlingGeneric Function, cg package
Arguments: header-control header-id label &key (index -1) justification width
Adds a new header to header-control, with programmatic name header-id and displaying label. The text in the header is justified according to the justification of the header-control (the value returned by default-header-justification applied to header-control) unless a value for justification is specified. Possible values are :left, :right, or :center. The width is the default width of the header-control (returned by default-header-width applied to header-control) unless a value for width is specified.
index is a fixnum indicating the position of the new header among the other headers on the header-control. A non-negative number indicates a position from the left side, where zero is the leftmost header, and a negative number indicates a position from the right side, where -1 is the rightmost header.
See the description of the header-control class/control.
Generic Function, cg package
Arguments: window hotspot
Adds hotspot, which must be an existing hotspot object, to a window.
See the description of the hotspot class.
Generic Function, cg package
Arguments: list-view list-view-item &optional (index -1)
Adds the new item, list-view-item, to list-view at index. An index of zero indicates the topmost position, 1 means second from the top, and so on. An index of -1 (this is the default) means the bottom-most position.
See the description of the list-view control.
Generic Function, cg package
Arguments: outline new-item parent-item-or-value &key no-redisplay position no-error-p
Adds the outline-item new-item to outline either as a top-level item or as a subitem of the item whose value is parent-item-or-value, at position among its siblings. new-item must be an instance of the outline-item class. outline must be an instance of the outline class.
parent-item-or-value may be either the parent outline-item under which to add the new item, or the parent item's value, or else nil to add the new item as a top-level item. Specifying the parent item by its value is typically convenient, but is less efficient since the item must first be looked up from its value. And if multiple items have this same value, then the wrong parent may be found unless the actual parent outline-item is specified. (If parent-item-or-value is non-nil and no outline-item can be found in outline that matches the specified value, then an error is signaled if no-error-p is nil, and nothing is done if no-error-p is true.)
This function searches only through the currently visible outline-items for parent-item-or-value. If parent-item-or-value specifies an item that is currently hidden (due to an ancestor item being closed), then an error is signaled unless no-error-p is true. As an alternative, (setf range) works regardless of whether the parent item is currently visible.
The value of position should be a non-negative integer, :end or nil. 0 means above all siblings. :end means below all siblings. nil means position according to the on-sort-predicate (if on-sort-predicate is nil or the function true (which always returns true) new-item is positioned at the top among its siblings.)
If no-redisplay is true, the outline will not be redisplayed by this function to reflect the change. You may wish to delay redisplay when there is more than one modification until all modifications are made.
If no-error-p is true, no error will be signaled if the requested action cannot be performed for any reason. Instead, nothing will be done. (Specifying this argument true does not protect against malformed calls to this function, such as specifying a value for new-item which is not an instance of outline-item.)
To change the whole set of child outline-items of a parent outline-item (or all of the top-level items of an outline control), an alternative is to call (setf range) on the parent outline-item or the outline control, passing a list of outline-items as the new value.
If no item was successfully added, then nil is returned. Otherwise two values are returned: (1) the outline-item that was added, and (2) the index of the new item within all currently visible items. (The index will be nil if the new item is not visible because the parent item is closed.)
Generic Function, cg package
Arguments: outline item-value parent-item-or-value &key kind (state :closed) range no-redisplay position no-error-p
Creates a new outline-item instance whose value is item-value, and adds the new item to outline as a child item of the item specified by parent-item-or-value. (If parent-item-or-value is non-nil and no outline-item can be found in outline that matches the specified value, then an error is signaled if no-error-p is nil, and nothing is done if no-error-p is true.)
This function searches only through the currently visible outline-items for parent-item-or-value. If parent-item-or-value specifies an item that is currently hidden (due to an ancestor item being closed), then an error is signaled unless no-error-p is true. As an alternative, (setf range) works regardless of whether the parent item is currently visible.
outline is the outline widget to which the new item is being added.
item-value is an arbitrary value for the new outline-item. See also add-outline-item, which takes an outline-item object instead.
parent-item-or-value may be either the parent outline-item under which to add the new item, or the parent item's value, or else nil add the new item as a top-level item. Specifying the parent item by its value is typically convenient, but is less efficient since the item must first be looked up from its value. And if multiple items have this same value, then the wrong parent may be found unless the actual parent outline-item is specified.
position indicates the index of the new item among its siblings. Zero (or nil) puts the item above all its siblings, 1 places it below the first sibling, and so on. The special value :end will put the item below all of its siblings.
If no-redisplay is true, the outline will not be redisplayed by this function to reflect the change. You may wish to delay redisplay when there is more than one modification until all modifications are made.
range may be a list of outline-item instances that will become the child items of the newly-created item, or (typically) nil to not add any child items at this time.
kind simply sets the kind property of the new item.
If no item was successfully added, then nil is returned. Otherwise two values are returned: (1) the outline-item that was added, and (2) the index of the new item within all currently visible items. (The index will be nil if the new item is not visible because the parent item is closed.)
See also add-sibling-outline-item, add-child-outline-item, remove-outline-item-value and outline-item-added.
Generic Function, cg package
Arguments: parent-section new-subsection &optional (index 0)
Adds a grid-row to the grid-row-section specified by parent-section and at the specified index among the rows of that section. An index of zero indicates the first (topmost) position. A huge number can be used for index to add to the end.
Alternately, (setf subsections) can be called to replace the entire set of rows of the row section.
See the description of the grid-widget class.
Generic Function, cg package
Arguments: outline &key value
Creates an outline-item that has the specified value, and adds it to the specified outline as a sibling of the currently selected item, if any, and otherwise as a top-level item. The item will be positioned just after the selected item when there is one, and otherwise at the very top of the outline.
This function is a specialization of the more general function add-outline-item-value, and could be used directly for an interactive command to create a sibling of the selected item.
Generic Function, cg package
Arguments: window &optional status-bar (number-of-lines (status-bar-number-of-lines window)) (font (status-bar-font window)) status-bar-class-name
Creates a status-bar dialog pane on window, unless there is already one there. (Only a single status-bar pane can be added to a window.) Re-sizes any other child windows on window in order to make room for the status-bar. Also moves any widgets (if on a dialog) upward to make room.
The status bar added is an instance of the status-bar class. You may wish to use a common-status-bar, in which case use add-common-status-bar.
The arguments are:
window: the window to get the status bar.
status-bar: if passed, should be either a status-bar that was removed from a window, or a status-bar created with make-window with a call like (make-window 'status-bar ...)
number-of-lines: the number of lines of text that should fit into the status-bar's static-text widget. The status-bar dialog will be made of sufficient height to fit the requested number of lines. Defaults to status-bar-number-of-lines applied to window.
font: the font to use in the static-text widget of the status-bar dialog pane. The status-bar dialog will be made of sufficient height to fit this font. Defaults to status-bar-font applied to window.
Generic Function, cg package
Arguments: tab-control tab-info-or-name label &key (index -1)
Adds a tab to a tab-control at a specified position and displaying a specified label.
tab-control is the existing tab-control widget to which the tab will be added.
tab-info-or-name is either an existing tab-info instance or a symbol to name a new tab. If a symbol, a new instance of the tab-info class having that name will be automatically created. If a tab-info instance, it may be an instance either of the tab-info class itself or of an application-defined subclass of tab-info.
label is a string to display on the tab. If tab-info-or-name* is a *tab-info object that already has a *label property, then nil may be passed here to use the *existing label.
index indicates the position at which to add the new tab. Zero will place the new tab at the leftmost position, 1 at the next leftmost position, and so on. A negative number indicates a position from the right end of the existing tabs, where -1 is the last (rightmost) position, -2 the next rightmost position, and so on. The default is -1 to add the new tab to the right of all of the existing tabs.
See the description of the tab-control class/control.
Generic Function, cg package
Arguments: menu menu-item &key position after (at-end t)
Adds menu-item to menu at a specified position among the current menu-items or after a menu-item given as the value of after. at-end is obsolete (use :position :end).
Returns the menu-item that was passed in after adding it to menu.
The arguments are:
menu: may be any menu, whether a menu-bar, pop-up-menu, or pull-down-menu.
menu-item: should be a menu-item.
position: may be either :start, :end, or a non-negative integer. :start adds the menu-item at the top of the menu. :end adds it at the bottom. An integer indicates an index into the list of menu-items, where zero indicates the top of the menu and any integer equal to or greater than the number of menu-items presently in the menu indicates the bottom.
after: may be either nil or a menu-item that is presently in the menu or the name of such a menu-item. If true and the menu-item is found in the menu, then the new menu-item is placed just below the after menu-item.
The position of the menu-item is determined by the after argument if it specifies a menu-item that is present in menu, and otherwise by the position argument. Note that a menu-item should only be added to one menu. If a similar menu-item must appear in more than one menu, create copies (by calling (make-instance 'menu-item) with identical arguments or with copy-menu-item) as necessary.
See also open-menu.
Backward compatibility note: All releases after 5.0 replace the at-end argument with the position and after arguments, but at-end will still work for backward compatibility. If at-end is true (and position and after are unspecified), then the menu-item is placed at the bottom of the menu, and otherwise at the top. at-end should not be specified simultaneously with either position or after; an error will be signaled if this is done.
Generic Function, cg package
Arguments: window* &optional *toolbar no-resize-toolbar no-resize-child-windows
Creates a toolbar dialog pane on window. The new toolbar is added just below any existing toolbars on the window, unless no-resize-toolbar is true, in which case the toolbar retains its current coordinates (which would make sense only for an existing toolbar that's passed in). Any other child panes are shaped smaller to make room for the new toolbar, unless no-resize-child-windows is true. Any components (if the window is a dialog) are moved lower to make room for the toolbar.
The new toolbar is created without any controls on it initially, unless you pass the optional toolbar argument to add a pre-existing toolbar dialog to the window rather than creating a new one. A pre-existing toolbar can be either a toolbar that was removed from this or another window, or an arbitrary toolbar created by calling make-window and specifying the toolbar class.
Alternately, you can use the Integrated Development Environment to build a window complete with toolbar and toolbar widgets that will be recreated all at once.
Generic Function, cg package
Argument stray-item &key window
Adds the specified tray-item to the system tray unless it is there already, in which case nothing is done. in-tray-p returns whether a tray-item is currently in the tray, and remove-tray-item removes a tray-item from the tray. A tray-item may be added and removed any number of times.
tray-item must be an instance of the tray-item class, as created with make-instance.
If window is specified, it should be the window that will be passed to tray-item-message when mouse events occur on the tray-item. If nil, then the application's frontmost top-level window whose state is either :normal or :maximized will be used; an error will be signaled if there is no such window.
An application would typically specify an icon for the tray-item before adding it to the tray. See tray-item-icon.
It is recommended that remove-tray-item be called on the tray-item before the application exits or its window is closed. This is not necessary, but the icon may otherwise continue to appear in the tray until the end user moves the mouse over it.
See the description of the tray-item class for an example.
Generic Function, cg package
Arguments: list-view
Determines how icons in list-view are laid out when they are arranged into a rectangular array. Such arrangement is done only when the layout-style of the argument list-view is either :small-icon or :large-icon. (See arrange-icons and auto-arrange.)
The value can be :top or :left. The default is :top. When the value is :top, the icons are first laid out in a row along the top of the window, then in a second row below that, and so on. When the value is :left, then the icons are first laid out in a column along the left side of the window, then in a second column beside that, and so on.
See list-view.
Generic Function, cg package
Arguments: menu-item
Determines whether the keyboard shortcut for this menu-item may be used while a modal dialog is invoked. Generally this property should be turned on only for those menu commands that may be applied within the context of a modal dialog and without requiring interaction with other windows, since the user should be interacting only with the modal dialog as long as it is shown.
allow-during-modality is a property of the menu-item class.
Generic Function, cg package
Arguments: outline
Returns the value of the ancestor-background-color property of an outline control. The value may be specified at creation time by passing the ancestor-background-color initarg to make-instance, or any time later by calling (setf ancestor-background-color)).
This is the color in which the background of ancestor outline-items of the currently selected item will be drawn if the highlight-ancestors property is true.
The value should always be an RGB color object, as made with make-rgb. The default value is a "slate blue" made with (make-rgb :red 235 :green 235 :blue 250).
Generic Function, cg package
Arguments: stream color-number rgb
Tells the operating system to insert the rgb color (see make-rgb) which is the rgb argument into the palette of stream at index color-number. Further, the OS is told not to share this color with other palettes because it needs to be reserved for color switching. stream should be a cg-stream.
Function, cg package
Arguments:
Returns a standard fixed-width font provided by the operating system. This is the suggested default fixed-width font.
Function, cg package
Arguments:
Returns a standard variable-width font provided by the operating system. This is the suggested default variable-width font.
Generic Function, cg package
Arguments: widget
This property has an effect only on the Windows platform.
This property of various widgets determines the value that *antialiasing* will have while drawing lines and filling areas in the widget. See *antialiasing* for an explanation of its effect.
The value can be set at creation time by passing the :antialias-lines initarg to make-instance, or any time later by calling (setf antialias-lines).
This is a property of chart-widget, plot-widget, lamp, grid-widget, and node-pane-mixin. For the grid-widget, *antialiasing* will be bound only by the built-in draw-cell methods; you would need to bind it in your own draw-cell methods to effect antialiasing in custom-drawn grid cells.
Generic Function, cg package
Arguments: widget
This property has an effect only on the Windows platform.
This property of various widgets determines the value that *antialiasing* will have while drawing text in the widget. See *antialiasing* for an explanation of its effect.
The value can be set at creation time by passing the :antialias-text initarg to make-instance, or any time later by calling (setf antialias-text).
This is a property of scrolling-static-text, outline, chart-widget, plot-widget, lamp, grid-widget, and node-pane-mixin. For the grid-widget, *antialiasing* will be bound only by the built-in draw-cell methods; you would need to bind it in your own draw-cell methods to effect antialiasing in custom-drawn grid cells.
Generic Function, cg package
Arguments: system
An app is an object containing internal information about the currently-running Lisp application.
(app *system*) (see app and *system*) returns the app object for the currently-running Lisp application. This property is read-only. It is a property of the system class.
Function, cg package
Arguments:
Returns a pre-defined icon showing a square with blank interior. In CG/JS mode this is actually a pixmap, which can be used as an icon in that mode. In Windows desktop mode it is the icon that is the value of the application-icon variable.
Generic Function, cg package
This function is no longer supported. It returned the application type of its project argument, but only standard-exe is currently supported.
Generic Function, cg package
Arguments: list-view &key align
This function moves the icons in a list-view control if needed so that they are aligned horizontally and vertically and spaced equally. This is done only if the current layout-style is either :large-icon or :small-icon, since otherwise the items always appear as a single vertical list. The items will be arranged according to the value of the alignment property of the list-view.
align determines the value of the alignment property that is in effect when the arrangement is done. If either :left or :top, then the alignment property is first set to this value, and the arrangement is then done using that alignment value. If nil, then the current type of alignment is used.
This function will probably be needed only if the list-view is resized and its auto-arrange property is false, or if the function (setf list-view-item-position) has been used on some of the list-view's items.
See list-view.
Generic Function, cg package
Arguments: window
Pops up a dialog containing three buttons asking the user whether to save changes made to window.
Returns one of :yes, :no or :cancel.
The position of the dialog when displayed is controlled by position-utility-dialog.
Function, cg package
Arguments: prompt button1 &optional button2 button3 button4 title stream &key topmost
This is another version of pop-up-message-dialog. A dialog is displayed with as many buttons (one, two, three, or four) as are specified non-nil. The user clicks on a button and the value of that button (the value specified as the argument) is returned.
If the user cancels the dialog by clicking on the close box or pressing the Escape key, ask-user-for-choice returns the same as if the rightmost non-nil button was clicked. If the user hits Enter, the value of button1 is returned. That is, the leftmost button (button1, which must be non-nil) acts as the default button and the rightmost non-nil button acts as the cancel button. If there is only one button (button2, button3, and button4 are all nil), then any action (clicking on it, pressing Escape, pressing Enter, or clicking on the close button) causes button1 to be returned.
If you have more than four choices, you can use ask-user-for-choice-from-list.
The arguments are:
prompt: should be a string. It will be displayed in the dialog.
button1: the value can be a symbol or a string naming the button, or a list whose first element is a symbol or string naming the button and whose second element is a help string. The button is labeled with the string or the print name of the symbol. If a help string is provided, it is displayed in the status bar when the cursor is over the button. If the user clicks on this button, the argument's value (a symbol, a string, or a list of a symbol or string and a string) is returned.
button2, button3, and button4: the value can be a symbol or a string naming the button, or a list whose first element is a symbol or string naming the button and whose second element is a help string, or nil. If the value is nil, the button is not displayed. The button is labeled with the string or the print name of the symbol. If a help string is provided, it is displayed in the status bar when the cursor is over the button. If the user clicks on this button, the argument's value (a symbol, a string, or a list of a symbol or string and a string) is returned.
title: this argument provides the title for the dialog. Its value should be a string. Note that all optional button arguments must be specified to supply a title (to preserve backward compatibility). Specify nil for a button that should not be displayed. If no title is specified, none is used.
stream: the owning window of the dialog; defaults to the stream returned by selected-window-or-screen. Note that all optional button arguments and the title must be specified to supply stream. Specify nil for a button that should not be displayed and for title if you want no title.
topmost: when this argument is true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application. Note that all optional arguments must be specified to specify a value for topmost.
The position of the dialog when displayed is controlled by position-utility-dialog.
Function, cg package
Arguments: title choice-list &key stream initial-value allow-multiple simple-click-toggle (on-print 'princ-to-string) on-change topmost width height on-list-item-mouse-in dialog-exterior-box
Displays a modal dialog with title title offering the choices in choice-list along with OK and Cancel buttons. Two values are returned: the value or list of values (if allow-multiple is true) chosen and t if the OK button is clicked; nil and nil if the Cancel button is clicked. (The second returned value allows the program to distinguish between the user selecting the value nil and canceling the dialog.)
The keyword arguments are:
stream: this keyword argument specifies the owner of the dialog. It defaults to the stream returned by selected-window-or-screen.
initial-value: specifies the value or values (if any) that should already be selected when the dialog appears, typically as a suggested default choice. The value may be either an element of choice-list or else nil to select no value. If allow-multiple is true, then the value may alternately be a list containing any subset of the choice-list elements. If the argument is not specified (as opposed to specifying nil), then the first choice in choice-list will be selected.
allow-multiple: if true, the first returned value is a list and the user may choose more than one value (with the shift or control keys in the typical Windows manner).
simple-click-toggle has an effect only if allow-multiple is true. In that case, if simple-click-toggle is true, then the user does not need to hold down the Control key while clicking in order to toggle individual choices. Note, however, that using this feature also disables the ability to choose a whole range of choices with a Shift-click. When this argument is nil (the default), Control-click toggles individual choices; Shift-click selects everything between the thing clicked on and a chosen item above, inclusive; and a click chooses an item and unchooses anything else selected, all of which is standard Windows behavior.
on-print: if specified, the value should be a function of one argument that returns a string. The strings resulting from applying the function to each element of the list will be used to print the elements of choice-list in the dialog. The value can be a function name or a function object. (See the similar on-print event handler for dialogs, whose value must be the name of a function of one argument that returns a string.) The default value is princ-to-string. Here is an example, where the choice-list contains integers and they are incremented by 1 before being displayed:
(ask-user-for-choice-from-list "X" (list 4 5 6)
:on-print
#'(lambda (x)
(format nil "~D" (+ 1 x))))on-change: the value may be either nil or a function or function name. If true, it is used as the on-change event handler for the item-list of the ask-user-for-choice-from-list dialog. The function will therefore be called as the user highlights each choice in the dialog. This may be handy for showing a help message for each choice. The function should take the three arguments widget, new-value, and old-value (as usual with an on-change handler), and should always return true (since returning nil would prevent the user from successfully selecting a choice). The default value of on-change is nil, which causes an internal on-change handler to be used.
topmost: when true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application.
width and height: these arguments determine the width and height of the dialog displayed. The positioning of the dialog is determined, then, by position-utility-dialog. width and height should not be specified if dialog-exterior-box is specified, but use of dialog-exterior-box is deprecated in favor of width and height.
on-list-item-mouse-in: nil or a function that will be assigned as the on-list-item-mouse-in property of the dialog's item-list during this call, for arbitrary side effecs as the user moves the mouse cursor over individual items in the list. This parameter was added in release 11.0.
dialog-exterior-box: if specified, should be a box (see make-box). The dialog will be the size of the box but the location will be specified by position-utility-dialog (the top and left of the box are ignored). Again, use of this argument is deprecated in favor of the width and height arguments described just above. No value should be specified for this argument if values are specified for width and height (which override this argument).
An alternative way to ask the user for a choice from a list, especially if the list of choices is small, is to call pop-up-menu, pop-up-lettered-menu, or pop-up-shortcut-menu. For four choices or fewer, ask-user-for-choice may be used. See also yes-no-or-cancel-list.
Function, cg package
Arguments: &key initial-color (title "Select a Color") (prompt "Use the widgets to specify a new color.") show-custom-colors disable-custom-colors stream
Displays a dialog for specifying a color value. Returns an RGB color value for the color that was selected, or initial-color if no color was selected. Except if the user cancels the interaction (by pressing the Cancel button on the dialog), then nil is returned.
initial-color should be an RGB color value (such as created by make-rgb), or else nil to default to some unspecified color.
title should be a string to display in the title-bar of the dialog. This has no effect in Windows desktop mode, where the Microsoft dialog does not support it. This parameter was added in release 11.0.
prompt should be a string to display in the body of the dialog to instruct the user what to do. This is used only in CG/JS mode. This parameter was added in release 11.0.
If show-custom-colors is specified true, then an extra section of the dialog that allows users to define custom colors in addition to the standard set is displayed initially. If nil, then the extra section is displayed only if the user clicks the button whose appearance is controlled by the next argument. This is implemented only in Windows desktop mode.
If disable-custom-colors is specified true, then the button that brings up an extra section of the dialog that shows custom colors is masked. This is implemented only in Windows desktop mode.
stream is the owner window for the dialog. This window and all of its owned windows and their descendants will be unavailable to the end user while the color dialog is present. stream defaults to the stream returned by selected-window-or-screen. It is also valid to specify (screen *system*) (see screen), which means that the dialog will not have an owner window and therefore will not disable any windows.
function, cg package
Arguments: &key initial-date (get-universal-time)) (title "Select a Date") (calendar-mode :month) (stream (selected-window-or-screen))
This function displays a modal dialog that contains a calendar widget, allowing the user to select a date.
initial-date is a universal time integer for the date that will initially be selected. The default is today.
title is a string to display in the title bar of the dialog. The default is "Select a Date".
calendar-mode is a keyword symbol for the type of date range that the calendar will initially display. See the calendar-mode property for the valid values. The default is :month to display one full month of individual dates. The value may also be nil to show the calendar in the mode that it was in when the user last exited the dialog.
stream is the owner window (or the screen) on which the dialog will be displayed. The default is the currently-selected window, if any, and otherwise the screen.
If the user cancels the dialog, then nil is returned. Otherwise four values are returned, all integers.
A universal time for the date that the user selected.
The year of that universal time.
The month (1 to 12) of that universal time.
The date (1 to 31) of that universal time.
See the calendar class for general information on the widget that is shown in the dialog. An additional feature of this dialog is that the user can double-click a date to immediately return that date from the dialog, as an alternative to first selecting a date and then either pressing the OK button or pressing the Enter key.
Function, cg package
Arguments: &key (prompt "Select a folder.") (stream (selected-window-or-screen)) root dont-go-below-domain browse-include-files include-edit-box new-dialog-style
Displays a dialog where the user can select an existing directory (also known as a folder).
The newer function ask-user-for-new-or-existing-directory has more options than this one and works the same on all platforms, and so may be a better choice in most cases. On the other hand, on the Windows platform this function will show the dialog that is provided by Microsoft, with its native look and feel. In CG/JS mode, this function simply calls ask-user-for-new-or-existing-directory, because there is no native JavaScript dialog to invoke instead. The rest of the description of this function is specific to Windows desktop mode.
The chosen directory is returned as a pathname object. Note that the directory is stored in a buffer, and if the buffer is too small then an error will be signaled. The buffer size is determined by file-selection-buffer-size. The default size is large enough to hold at least 12 pathnames so this should not be a problem for this function, which returns one pathname only.
Note too that it is not possible to specify the initially-selected directory or which subdirectories are initially open in the hierarchy that is presented.
The arguments are:
prompt: an informational string explaining to the end user what they need to choose. The string appears in the body of the dialog. If unspecified or nil, the prompt "Select a folder." is used.
stream: the window or screen that will serve as the owner of the dialog while it is present. The dialog will be modal with respect to this owner window and all of its child windows and owned windows (that is, the user will not be able to access these windows while the dialog is present). Defaults to the stream returned by selected-window-or-screen.
root: This argument is no longer working for undetermined reasons. We recommend using the more versatile function ask-user-for-new-or-existing-directory instead, specifying the initial-directory argument, which is the equivalent of root for that function. When this argument is working, the value should be a pathname, path namestring, or nil, indicating the directory that will appear as the root node in the dialog's directory tree. Only this directory and its subdirectory descendents will be presented for selection by the end user. nil means to include all available file systems. The final slash is optional when either a pathname or namestring is passed.
dont-go-below-domain: if true, then network folders below the domain level, (as defined by MSDN), will be excluded from the tree of choices (though network folders above the actual directories may still be viewed). If nil, directories on both the local computer and networked computers are accessible.
browse-include-files: if true, the dialog will display regular files in addition to directories, and either a directory or other file may be chosen by the end user and returned.
include-edit-box: if true, then a text-entry widget will be included on the dialog. If the absolute (complete) path namestring of an existing folder (with or without the final backslash) is typed or pasted here, it will be used instead of the folder that's selected in the outline widget (if any).
new-dialog-style: if true, then Microsoft's "newer style" is used, where the dialog is resizable, is centered on the screen, and has a "Make new folder" button for creating a new directory. The new style also provides a right-click menu in the outline widget for doing things such as renaming a folder. These features used together allow the user to create and then rename a new folder, though more awkwardly than with ask-user-for-new-or-existing-directory.
See also ask-user-for-existing-pathname and ask-user-for-new-pathname, which ask the user for a file rather than a directory.
Function, cg package
Arguments: prompt &key initial-directory initial-name stream allowed-types multiple-p change-current-directory-p share-aware-p default-extension (buffer-size (file-selection-buffer-size (configuration *system*))) title
This function provides the service of prompting for one or more existing pathnames.
If multiple-p is nil (the default), returns the pathname of the selected file, or nil if none was chosen. If multiple-p is true, returns a list of selected files (even if only one is selected) or nil if none is selected. prompt should be a string explaining what is to be done with the selected file (e.g. "Choose file to open").
The arguments are:
initial-name: the filename shown initially for selection. It can be any relative filename with respect to the initial directory (the value of :host). If nil or " " (the empty string), the initial name will appear as the currently allowed type, such as "*.cl". The default is " ". A non-nil value may be either a namestring or a pathname object.
initial-directory: the initial directory from which to select the file or from which to change directory. If this value is unsupplied, the default depends on the value of the ide:context-sensitive-default-path configuration property, but in most cases the most recent value is used. The value of *default-pathname-defaults* is used initially.
stream: specifies the parent window for the dialog that pops up. Defaults to the stream returned by selected-window-or-screen.
allowed-types: specifies what types of files appear in the dialog's list of existing files. The value is a list where each member specifies one of the choices in the drop-down list of file type choices. Each list member is a cons of (1) the string to appear in the list of file type choices and (2) a string of the form "*.foo;*.bar;..." that indicates the file type(s) that it represents. The first choice is the one that is initially in effect. For example, the value (("Text Files" . "\*.txt")("Pixmap Files" . "\*.bmp;\*.jpg;\*.jpeg")) would initially display all files whose type is "txt", and also allow the user to select the second choice to instead display all files of the types "bmp", "jpg", and "jpeg". (Users can always type in some other file if desired.) The default value of this argument is (("All files" . "\*.\*")) to display all files.
multiple-p: a Boolean which, if true, allows the user to select more than one file; the list of selected pathname strings is returned. If nil, only one file may be selected and the returned value is a pathname string or nil, if the user cancels the dialog. The default is nil.
change-current-directory-p: a Boolean which, if true, changes the Microsoft Windows current directory to be the final selected directory when you exit or cancel the dialog. If nil, the current directory is left unchanged. Default is nil.
share-aware-p: a Boolean which controls whether a file that is currently opened by another application can be selected. If nil (the default), the file cannot be selected. If true, the file can be selected.
default-extension: the value should be either nil or a string that names a default pathname extension. This value is used only if the end user has selected an allowed type such as "All Files (.)" on the file selection dialog that does not specify a particular type, and they type in a filename with no extension. In that case, the pathname returned by this function will have default-extension as its pathname-type. An exception is that if default-extension is the null string, it will result in a pathname whose type is nil rather than the null string, just as if default-extension were nil.
buffer-size: an integer specifying the size of the buffer that's used to return the seleced pathnames. This is used only on the Windows platform. The default value is (file-selection-buffer-size (configuration *system*)) (see file-selection-buffer-size, configuration, and *system*. The default should always be sufficient when asking for new pathnames, where the filenames must be typed in.
title: a string to display in the title-bar of the dialog. This is used only in CG/JS mode, due to the native Windows file dialog not offering this. This parameter was added in release 11.0.
This function uses the standard Common Dialog supplied by the platform's underlying windowing system for file selection. Internal Allegro CL file selection dialogs use this function.
See also ask-user-for-new-pathname and ask-user-for-directory. And see file-selection-buffer-size.
Function, cg package
Arguments: &key stream-for-font initial-font fixed-width-only-p minimum-size maximum-size initial-point-size stream
Pops up the Windows Common Dialog for font selection. This function is also used internally by Allegro CL for font selection. If a font is selected, two values are returned: the font selected and the point size specified by the user. (See below for why the point size might be useful.) If s/he cancels, the single value nil is returned.
The arguments are as follows:
initial-font: if passed, should be a font object to be displayed initially in the dialog; if not passed, then no initial font is displayed.
fixed-width-only-p: if true, then the choices displayed in the dialog will be only those fonts where every character is the same width, such as :courier.
minimum-size: if passed, should be a positive integer denoting the minimum acceptable point size of the font; all sizes are still listed in the dialog, but a pop-up error dialog will prevent the user from returning an unacceptable size.
maximum-size: if passed, should be a positive integer denoting the maximum acceptable point size of the font.
initial-point-size: If passed, overrides the pixel-size of the font indicated in the initial-font. This parameter is supplied because the font dialog displays sizes in points, and it is difficult to automatically map a common graphics pixel size to the desired point size for display.
stream: the owning window of the font dialog. All owned windows of this window will be unavailable to the end user while the font dialog is being invoked. Defaults to the stream returned by selected-window-or-screen.
stream-for-font: The list of font choices displayed on the dialog will be the set of fonts available for this stream. If the selected font is to be used in a window, then the default value of (screen *system*) (see screen and *system*) should be appropriate. But if the selected font is to be used on a printer stream, then you may want to pass the printer stream as the value of this argument so that the list of choices will include fonts provided by the printer driver.
When selecting a font, one potential source of confusion is that while Allegro CL specifies font sizes in pixels, the Common Dialog specifies them in points. So the size that you select from the dialog will not be the same as the size value in the returned font object. But the point size specified will be returned as the second returned value -- see the next paragraph. Allegro CL uses pixel-size programmatically so that the same units are used for all sizes associated with a window --fonts, window dimensions, drawing, etc. The point sizes that appear in the Common Dialog, on the other hand, will be similar to those that are familiar from choosing fonts interactively in other applications.
The point size is provided as the second returned value to permit better communication with users. Suppose a user of your application is presented with the dialog displayed by this function and asked to choose a font for use in some table of data that the application will display. Suppose further that the program determines that the font chosen is so large that it will cause line truncation or wrapping. A dialog might be displayed telling the user that the chosen font will cause problems and that s/he might wish to choose a smaller font. Mentioning the point size in that dialog will be more meaningful to users (because it corresponds to the value they actually chose) than mentioning the pixel size, which is a value they likely will not have seen. Note that both the point size and the pixel size are contained in the Windows font structure, from which Allegro CL gets all font information. Allegro CL does not itself derive a pixel size from the point size.
Function, cg package
Arguments: &key (owner (selected-window-or-screen)) (type :either) (always-show-text-box t) title prompt position width height (scope :all) (special-folders '((:personal #+mswindows "My Documents" #-mswindows "Home"))) (create-if-new t) initial-directory initial-subdirectory show-initial-directory-siblings (show-local-file-systems t) look-ahead (prompt-for-password-if-needed t) (focus-on-new-subdirectory (eq type :new)) select-file (allowed-types '(("All Files" . "*.*"))) default-extension initial-name close-subtrees-on-close show-initial-directory-children search-network-globally
This function displays a modal dialog that allows the user to specify a new or existing directory (also known as a folder). The directory can be specified either by selecting it in the outline widget, or entering an absolute path namestring in the text-entry widget, or by entering a relative path namestring in the text-entry widget that is relative to the directory that is selected in the outline. It does not matter whether the user types a final slash character after a directory name in the text-entry widget. Help strings at the bottom of the dialog guide the user in specifying a complete path.
Two values are returned: (1) A pathname for the directory that was specified by the user (or nil if the user cancels the dialog), and (2) either t or nil, indicating whether the directory is a new one (that is, nil if there already was a directory at the specified path, and t if there was not).
The arguments are:
owner: either the screen or a window. Defaults to the stream returned by selected-window-or-screen. If a window, then the modal dialog will be owned by this window (and therefore will stay in front of it) and will be modal with respect to this window (meaning that interactive gestures are disabled in all other windows of the window hierarchy that has this window as its root).
type: a keyword indicating whether a new or existing directory (or either) is being requested. The value must be one of the following three symbols:
:either (the default), meaning the user may specify either a new or an existing directory.
:new, meaning only a new directory may be specified.
:existing, meaning only an existing directory may be specified.
For either :new or :either, a text control will always appear below the outline for entering a new subdirectory name. For :existing, this control will appear only if always-show-text-box is true.
always-show-text-box: if true, then the text-entry widget for specifying all or part of the path textually will be always be included on the dialog; if nil, then the text-entry widget will be included when the type argument is :new or :either, but not when it is :existing. The default value is true.
title: a string to display in the title-bar of the dialog. The default string depends on the type argument.
prompt: a string to display in the body of the dialog to instruct the user what to do. The height of the prompt area in the dialog will be adjusted automatically so that the prompt string fits.
position: either a position object (see make-position) indicating the screen position of the upper-left exterior corner of the dialog, or nil (the default) to use a default position. The default position is determined by center-modal-children and center-all-modal-dialogs-on-screen, as with the other built-in utility dialogs.
width: either a positive integer indicating the exterior pixel width of the dialog, or nil to use the width that was used most recently with the specified owner, including interactive resizing that the user may have done. Initially a moderate default width is used.
height: either a positive integer indicating the exterior pixel height of the dialog, or nil to use the height that was used most recently with the specified owner, including interactive resizing that the user may have done. Initially a moderate default height is used.
scope: a keyword indicating whether local disks or network shares (or both) are to be included in the outline. The value must one of the following symbols:
:all (the default), meaning both local disks and network shares are included.
:local, meaning only local disks are included.
:remote, meaning only network shares are included.
special-folders: a list of special directories to include as top-level items in the outline widget, alongside the usual top-level items for local and remote file systems. The value should be a list where each member is a list of at least two things: (1) one of the keyword values that can be passed to the function win:special-windows-directory, (2) a string to display for the folder in the dialog, and (3) an optional third boolean value that indicates whether the outline item for the folder should initially be open to reveal its child folders.
The default value is ((:personal #+mswindows "My Documents" #-mswindows "Home")), which will include a "My Documents" item on Windows and the home directory item on Linux. On Linux, :personal is currently the only indicator that will be used. On Windows, the indicator :personal should be used for the "My Documents" folder, because the :my-documents argument to win:special-windows-directory does not seem to work.
Here is an example value that includes some additional possibly useful values on the Windows platform:
:special-folders '((:personal #+mswindows "My Documents"
#-mswindows "Home"
t) ;; show child folders initially
(:recent "My Recent Documents")
(:app-data "Application Data")
(:desktop "Desktop")))create-if-new: this argument is used only if the user specifies a new subdirectory. In that case, if create-if-new is true (the default), then the specified subdirectory is created automatically before its pathname is returned, and otherwise it is not. In any case, the second returned value will be true if and only if a new subdirectory was specified. Multiple directories will be created automatically if the specified path ends with a chain a multiple subdirectories that do not yet exist.
show-initial-directory-children: this argument is used only when an initial-directory argument is specified. If nil (the default), then no children of the outline-item for the initial directory are visible when the dialog appears. If true, then that outline-item is opened to reveal any immediate subdirectories of the initial directory.
show-local-file-systems: if true, then the top-level item for local disks or file systems will initially be open to reveal the individual file systems; if nil, then it will not be. The default value is true.
initial-directory: either nil (the default) or a pathname or namestring indicating the directory to which the outline will initially be opened. The specified directory (if any) will also be initially selected. This option is useful for suggesting the area of the directory hierarchy in which the user may want to select a directory, and for making it easier for the user to browse to the probable desired directory. When this argument is nil, the outline is always opened to show only the local disks and/or the network shares, and the topmost outline-item will initially be selected.
If this argument is a namestring rather than a pathname, it does not matter whether the namestring contains a final slash. Also, if the specified directory does not exist, the outline will still initially be opened to any upper levels of the specified directory that do exist. It is also OK to pass in the full pathname of a file that is (or could be) in the desired directory; the pathname name and type will be ignored.
initial-subdirectory: either nil (the default) or a string to display initially in the text control where the user may enter a new subdirectory name. This argument is ignored if the type argument is :existing (in which case the text control for a new subdirectory will not appear at all). When nil, this control will be empty initially.
show-initial-directory-siblings: this argument is used only when an initial-directory argument is specified. If nil (the default), then each level of the outline that is opened in order to display the initial-directory will show only the single child item that leads to the specified initial-directory. If true, then all siblings of each opened item will also be shown initially. The advantages of each choice are that the first shows less clutter, while the second provides more initial context. The user can navigate to any directory in either case, and a "partially open" outline-item in the nil case will show a plus icon to indicate that it has more children in addition to the one that it's already showing.
look-ahead: if nil (the default), then whenever an outline-item is opened to show its subitems, the icons for each subitem will always initially indicate that the subitem may be opened to show further subitems, even if in fact there are no further subdirectories for some or all of the newly-displayed directories. If true, then whenever new subitems are shown, the dialog will "look ahead" to see if each of the newly displayed subdirectories has any further subdirectories, and will display appropriate icons for each item to inform the user whether there will be anything further to see if each displayed item is opened. The advantages of each choice are that the first is faster, while the second provides additional useful information to the user. This option may be particularly slow for network shares.
prompt-for-password-if-needed: if true (the default), then if the user attempts to open a network share but the user's default username and password are not correct for that share, than a dialog is shown to allow the user to enter a different username and password. If nil, then a simple beep indicates when the user may not open a network share.
focus-on-new-subdirectory: if this argument is true and a valid initial-directory argument was specified, then the keyboard focus will be initially in the text control for typing in a new subdirectory name. Otherwise the keyboard focus will be initially in the outline control of the dialog. The default for this argument is true if the type argument is :new, and is otherwise nil. This option may be useful if the application is asking the user for a new subdirectory when the probable parent directory is known (and passed as the initial-directory argument); in this case the user can typically type in the new subdirectory name immediately and return.
select-file: whether the user can select a file or a directory. nil means that the user can select a directory only. :single means that the user can select one file. :multiple means that the user can select one or more files in the same directory (in which case the returned value is a list of pathnames rather than a single pathname). This parameter was added in release 11.0.
When selecting a file, this dialog (which is written in Common Graphics) is an alternative to the standard dialog of the underlying windowing system that is shown by ask-user-for-existing-pathname and ask-user-for-new-pathname. In CG/JS mode, those functions always calls this one internally, due to the lack of a built-in dialog for selecting a file on the server machine.
allowed-types: a list of file type specifiers that works as in ask-user-for-new-pathname. This is used only when select-file is true. This parameter was added in release 11.0.
default-extension: nil or a file type string like "txt". This is used only when select-file is true and this extension is a string, in which case it will be added to the file path if a file name is typed without a file type. This parameter was added in release 11.0.
initial-name: nil or a file name string that will be displayed initially in the widget for entering a file name. This parameter was added in release 11.0.
close-subtrees-on-close: the close-subtrees-on-close property of the outline control will be set to the value of this argument for this call. The default is nil for each call.
search-network-globally: This argument is used only on the Windows platform. To find the networked machines to list, a true argument will search the network "globally", whereas nil (the default) will search only "in the current context". The default is nil. This argument is passed (as the value of the global keyword argument) to win:network-machines; see that function for more information. This argument applies to Microsoft Windows only.
The dialog displays a file folder for each outline-item that represents an actual directory that may be returned. On Windows, this excludes the two root items for all "Local Disks" and "Network Machines" plus each network share (because only the descendent items of each share represent actual directories). These non-directory items will display a simple triangle icon instead of a file folder.
The OK button on the dialog will be disabled if no directory that may be returned is currently specified. This includes whenever a non-directory outline-item is selected. If the type argument is :existing (and always-show-text-box is true), this also includes when the text-entry widget contains text that does not name an existing directory. And if the type argument is :new, this also includes when the text control for the new subdirectory name is empty or contains an invalid directory name. At these times, the user may not exit the dialog by pressing the OK button or by pressing ENTER, but they may always exit by canceling the dialog (as usual, by pressing the ESCAPE key or the Cancel button or clicking the small close button in the frame).
On Windows, if the directory-selecting dialog that is provided by Microsoft is desired for its native look and feel, then the alternate function ask-user-for-directory will display that dialog. But that function has fewer options than this one.
Function, cg package
Arguments: prompt &key initial-name initial-directory stream allowed-types multiple-p change-current-directory-p warn-if-exists-p share-aware-p default-extension (buffer-size (file-selection-buffer-size (configuration *system*))) title
This function provides the service of prompting for one or more new pathnames. It displays a file choice dialog which can be used to specify the directory component. Typing the new name into the File field specifies the filename.
If multiple-p is nil (the default), returns the pathname of the selected file, or nil if none was chosen. If multiple-p is true, returns a list of pathnames of the selected files (even if only one is selected) or nil if none is selected. prompt should be a string explaining what is to be done with the selected file (e.g. "Select new filename for file").
The arguments are:
initial-name: the filename shown initially for selection. It can be any relative filename with respect to the initial directory (the value of :host). If nil or "" (the empty string), the initial name will appear as the currently allowed type, such as "*.cl". The default is "". A non-nil value may be either a namestring or a pathname object.
initial-directory: the initial directory from which to select the file or from which to change directory. If this value is unsupplied, the default depends on the value of the ide:context-sensitive-default-path configuration property, but in most cases the most recent value is used. The value of *default-pathname-defaults* is used initially. In earlier releases, this argument was called host. host is still accepted in place of initial-directory. Do not specify both.
stream: specifies the parent window for the dialog that pops up. Defaults to the stream returned by selected-window-or-screen. See screen and *system*.
allowed-types: specifies what types of files appear in the dialog's list of existing files. The value is a list where each member specifies one of the choices in the drop-down list of file type choices. Each list member is a cons of (1) the string to appear in the list of file type choices and (2) a string of the form ".foo;.bar;..." that indicates the file type(s) that it represents. The first choice is the one that is initially in effect. For example, the value (("Text Files" . "\*.txt")("Pixmap Files" . "*.bmp;*.jpg;*.jpeg")) would initially display all files whose type is "txt", and also allow the user to select the second choice to instead display all files of the types "bmp", "jpg", and "jpeg". (Users can always type in some other file if desired.) The default value of this argument is (("All files" . "\*.\*")) to display all files.
change-current-directory-p: a Boolean which, if true, changes the Microsoft Windows current directory to be the final selected directory when the user selects a file. If nil, the current directory is left unchanged. Default is nil.
multiple-p: a Boolean which, if true, allows the user to name more than one file; the list of selected pathname strings is returned. If nil, only one file may be selected and the returned value is a pathname string or nil, if the user cancels the dialog. The default is nil.
It is not clear how useful this option is but we include it because the operating system allows it. Users have to type the filenames into a dialog. Multiple filenames must be enclosed in double quotes and be space delimited ("foo.cl" "c:\tmp\bar.fasl").
share-aware-p: a Boolean which controls whether a file that is currently opened by another application can be selected. If nil (the default), the file cannot be selected. If true, the file can be selected.
warn-if-exists-p: a Boolean which, if true, pops up a warning dialog if the user selects a file that already exists. If nil, returns the existing filename string without complaint. Default is t.
default-extension: the value should be either nil or a string that names a default pathname extension. This value is used only if the end user has selected an allowed type such as "All Files (.)" on the file selection dialog that does not specify a particular type, and they type in a filename with no extension. In that case, the pathname returned by this function will have default-extension as its pathname-type. An exception is that if default-extension is the null string, it will result in a pathname whose type is nil rather than the null string, just as if default-extension were nil.
buffer-size: an integer specifying the size of the buffer that's used to return the seleced pathnames. This is used only on the Windows platform. The default value is (file-selection-buffer-size (configuration *system*)) (see file-selection-buffer-size, configuration, and *system*). The default should always be sufficient when asking for new pathnames, where the filenames must be typed in.
title: a string to display in the title-bar of the dialog. This is used only in CG/JS mode, due to the native Windows file dialog not offering this. This parameter was added in release 11.0.
This function uses the standard Common Dialog supplied by the platform's underlying windowing system for file selection. Internal Allegro CL file selection dialogs use this function. See ask-user-for-existing-pathname and ask-user-for-directory. See also file-selection-buffer-size.
Function, cg package
Arguments: prompt string1 option1 option2 &optional prompt2 string2 title stream cursor-at-end multi-line dialog-width
Displays a modal dialog prompting for one or two strings. Prompts for one string if the prompt2 and string2 optional arguments are not supplied or are supplied as nil. Prompts for two strings if prompt2 and string2 are supplied and are true. The string arguments are copied so string1 and (if supplied) string2 will be unchanged after this function returns.
The option1 and option2 arguments provide titles for buttons that appear on the dialog. Clicking a button causes the dialog to exit and the function to return. Each of these values may be either a string or a symbol, and a tilde character (~) in the string or symbol name indicates that the next character should be an underlined access character for the button.
This function returns four values. The first two are the strings as modified by the user except that the second value will be nil when the optional prompt2 and string2 arguments are not passed or are nil. As the third value, ask-user-for-string returns the string which is the value of the selected button argument (that is, option1 or option2 depending on which button the user clicks).
The fourth value indicates whether the user accepted or canceled the dialog. The value is t if the user either clicked the option1 button or pressed the ENTER key, and nil if the user either clicked the option2 button or pressed the ESCAPE key to cancel the dialog. In a sense, this repeats the information in the third returned value, since a string comparison such as
(when (string= third-value "~OK")
<process-the-string>)The fourth value allows a simpler test such as:
(when fourth-value <process-the-string>)This also removes the need to hardcode the button label twice or to let bind it.
The title argument (if supplied) should be a string and provides the title of the dialog. The prompt, string1, option1, and option2 arguments should also be strings.
The stream argument indicates the owner window for the dialog. It defaults to the stream returned by selected-window-or-screen.
If cursor-at-end is true, then the text cursor will initially be at the end of the initial string, to facilitate extending the suggested string. If nil, then the entire string will initially be selected, to facilitate replacing the string.
multi-line specifies whether the text-editing widgets allow editing multiple lines of text that contain newline characters, rather than only a single line. The functions pop-up-string-dialog and pop-up-strings-dialog also have this option as a keyword parameter, which is nicer than the unfortunate optional arguments of this function that are still used for backward compatibility. Any true value means to use a multi-line widget, and an integer value can be used to also specify the pixel height of the multi-line-editable-text widgets. This parameter was added in release 11.0.
dialog-width is the interior width of the dialog in pixels. The default width is 480. (The height is always determined automatically from the needed heights of the widgets.) This parameter was added in release 11.0.
Note several things:
The names of the buttons (provided by the option1 and option2 arguments) do not have effect in themselves. Even though the button named "Cancel" is clicked, nothing is canceled. The string "Cancel" is returned as the third value and the program must interpret the returned value to act appropriately.
Pressing ENTER has the same effect as clicking on the button associated with option1. Pressing ESC has the same effect as clicking on the button associated with option2. Pressing the space bar is not equivalent to pressing ENTER (as it often is with dialogs) because the space is interpreted as a character in one of the strings.
Even if a string is unmodified by the user, a copy rather than the original argument is returned.
The position of the dialog when displayed is controlled by position-utility-dialog.
See also pop-up-string-dialog and pop-up-strings-dialog. Their return values include the number of the button pressed and thus it may be easier to know what the user did using those functions rather than this one.
(ask-user-for-string
"Enter the correct answer and win a beautiful lounge suite."
"default answer" :~OK :~cancel nil nil "Answer Box"
(selected-window (screen *system*)))A typical usage of the returned string or strings would be to pass them to string-search or string-replace.
Generic Function, cg package
Arguments: window
Returns as four multiple values the attachment properties of window. These determine how window's size changes when its parent is resized. The issue is whether the window should scale with its parent or should stay the same size and whether the distance from a side of the child window to the corresponding side of the parent window should stay constant or should scale with the resizing. The four values are returned by this function (as multiple values). They specify the attachment behavior of the left, the top, the right, and the bottom of window, respectively.
The possible values for :left-attachment and :right-attachment are the keywords :left, :right, and :scale. :left means maintain the same distance from the parent's left side as before the parent was resized -- if the distance was 30 pixels before it is 30 pixels after the parent's resizing. :right means keep the distance to the right side constant. :scale means keep the ratio of the distances from the left and right sides constant -- if the side was half way between before, it is half way between after.
The possible values for the :top-attachment and :bottom-attachment are the keywords :top, :bottom, and :scale. :top means maintain the same distance from the parent's top as before the parent was resized -- if the distance was 30 pixels before it is 30 pixels after the parent's resizing. :bottom means keep the distance to the bottom constant. :scale means keep the ratio of the distances from the top and bottom sides constant -- if the side was half way between before, it is half way between after.
bottom-attachment, left-attachment, right-attachment, and top-attachment return the individual attachment properties.
Generic Function, cg package
Arguments: list-view
A boolean value indicating whether a list-view control will automatically arrange its list-view-items back into a rectangular array whenever an item is moved or the list-view is resized. This is done only when the layout-style of the list-view is either :small-icon or :large-icon. If nil (the default), then no automatic arrangement is done. If t, then automatic arrangement is done. The arrangement is done when setting this property to t as well.
For example, if the attachment properties (top-attachment, etc.) of a list-view control are set up so that the list-view is resized whenever the end user resizes its parent dialog, then the icons will be re-arranged to fill the new size of the list-view control if auto-arrange has been turned on.
A current incapacity of the list-view control is that it is not allowing the end user to drag list-view-items to new arbitrary positions, as it should when the layout-style is either :small-icon or :large-icon. But if a list-view-item is moved programmatically by calling (setf list-view-item-position), then auto-arrangement will still occur, and place the item back into the rectangular array position that is closest to the position to which the list-view-item was moved.
See list-view.
Generic Function, cg package
Arguments: column
When called on a list-view-column, modifies the width of the column so that the longest string in the column has just enough room. When called on a list-view control, auto-sizes all of its columns at once. See the description of the list-view control.
Generic Function, cg package
Arguments: text-edit-pane
This function has an effect only on the Windows platform.
Returns true or nil to indicate whether text-edit-pane (a text-edit-pane) will automatically switch to a different font when needed in order to properly display particular characters that are inserted into it. The value may be set when creating the window by passing an automatic-font-changing initarg to make-window, or any time later by calling (setf automatic-font-changing). The default value is nil.
This feature is typically used when the text-edit-pane might contain multibyte characters that are not available in some fonts. It can also be useful for Asian characters even when the text-edit-pane's official font contains the characters if it does not provide sufficient horizontal space to display wider characters readably.
If this features changes parts of the text to different fonts, CG does not actually know about that, and font will still return the single official font that was assigned to it by the application. On the other hand, get-character-format will return the name of the font face that is actually in use at the current text cursor position.
This function is a direct hook into the IMF_AUTOFONT option of Microsoft's RichEdit control. Font changes that this option makes may be rather unpredictable, and so setting the font property of a text-edit-pane to a font that you know is adequate may be preferrable to using this option.
See also dual-fonts-for-languages.
Generic Function, cg package
Arguments: calendar-widget
This property of a calendar widget determines whether the width and height of the widget will be automatically adjusted so that it is just big enough to fit the widget's contents when it's drawn according to its various properties. Properties that can affect the size include row-padding, column-padding, border-margin, title-margin, and calendar-title-font. Further, the pixmaps used to identify where to click to get the next and previous calendar pages (identified by increment-pixmap-name and decrement-pixmap-name) also affect sizing.
If the value is true, then automatic resizing will be done when the widget is created and when any of those properties are modified thereafter. If the value is nil, then the calendar cells will be spread evenly over the available area instead.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: standard-object
Returns true or nil as standard-object (typically a component or menu-item) is or is not available. An unavailable object cannot be selected or chosen. It is usually displayed with a visual clue that it is unavailable (i.e. it is dimmed or grayed out).
The value returned can be changed with setf and this function.
Function, cg package
Arguments:
Returns a list of the clipboard formats that are currently on the Windows clipboard. When a copy is done, applications typically clear all values from the clipboard and then post only those formats that apply to the object being copied. If rich text was most recently copied to the clipboard, then the list returned from this function may be (:text :rich-text). The only valid clipboard formats at this time are :text, :rich-text, and :pixmap. The :pixmap format reflects the "device-independent bitmap" Windows clipboard format; Common Graphics does not support the "device-dependent bitmap" format.
See cg-rich-text.html for information about rich text editing in Common Graphics. See also cg-clipboard.html.
Generic Function, cg package
Arguments: grid-column
Returns a function that returns whether each of the grid cells in a particular column of a grid-widget is currently accessible to the user, or else returns nil to determine the availability in other ways (see cell-available). The default value is nil.
The available-reader function is a property of a particular grid-column, and is called once for each grid-row that intersects that column to determine the availability of the cell at the intersection of that row and column. The function should take one argument, which is the data-object of a grid-row. If the attribute represented by the grid-column should currently be accessible to the user for the data-object that is passed to the function, then the function should return true, and otherwise it should return nil. When not available, a grid-cell appears grayed out and its value may not be modified by the user.
This property value may be specified as either a function name symbol (which would be more debuggable), or a function object (which may be slightly faster, though probably insignificantly), or nil.
Example: In the employee grid example, each grid-row represents an employee. If the "Full Time?" grid-column had an available-reader function, then the system would periodically pass an employee to that function, and the function should return true if the "Full Time?" cell for that employee should currently be accessible to the user. The employee grid example can be found on the Examples tab of the Navigator dialog.
NOTE: An application does not call the available-reader function; it supplies the available-reader function by calling (setf available-reader) or by passing the :available-reader initarg when calling make-instance to create a grid-column. The specified function is then called automatically by the system as needed.
available-reader is a property of the grid-column and row-header-column.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the axis-color property of a chart-axis. The value may be set at creation time by passing the :axis-color initarg, or any time later by calling (setf axis-color).
axis-color is the color that is used to draw a chart-axis of a chart-widget, including its tic marks. The value should be an RGB color object (see make-rgb) or else nil to default to the system-edge-shadow-color. The default value is nil.
The text on an axis is drawn in other colors. See axis-label-color, major-label-color, and minor-label-color.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the axis-label property of a chart-axis. The value may be set at creation time by passing the :axis-label initarg, or any time later by calling (setf axis-label).
axis-label is the label that is drawn along the length of a chart-axis on a chart-widget to indicate the meaning of the axis. The value should be a string or else nil to avoid drawing a main label on the axis at all. The default value is nil.
The string will be drawn in the axis-label-color and axis-label-font of the axis.
The chart will provide space for the label only when it is a string rather than nil. Only space for a single line of text is provided, unlike chart properties such as title, subtitle, and footnote, so the text should be no longer than the axis itself.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the axis-label-color property of a chart-axis. The value may be set at creation time by passing the :axis-label-color initarg, or any time later by calling (setf axis-label-color).
axis-label-color is the color that is used to draw the single axis-label along a chart-axis of a chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of black.
The tic mark labels are drawn with the major-label-color and minor-label-color properties.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the axis-label-font property of a chart-axis. The value may be set at creation time by passing the :axis-label-font initarg, or any time later by calling (setf axis-label-font))
axis-label-font is the font that is used to draw the single label along a chart-axis of a chart-widget. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 14).
The tic mark labels are drawn with the major-label-font and minor-label-font properties.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the axis-width property of a chart-axis. The value may be set at creation time by passing the :axis-width initarg, or any time later by calling (setf axis-width).
The thickness, measured in pixels, of the stem of a chart-axis of a chart-widget. The value should be a non-negative integer. The default value is 3.
Zero will avoid drawing the axis stem altogether, though the axis tic marks will still be drawn according to major-tic-length, major-tic-width, minor-tic-length, and minor-tic-width.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: *standard-object *
Returns the background color for standard-object if one has been specified for it, and otherwise returns nil. (By contrast, effective-background-color will always return a color, by calling default-background-color when background-color returns nil.)
The background-color is the color that is used to erase the object's drawing area (such as by clear-page) before its graphical content is drawn in the object's foreground-color. It is also used for drawing by functions such as erase-line and erase-contents-box. foreground-color and background-color apply to windows, dialog-items, button-infos (of a multi-picture-button), and outline-items (of an outline).
A background color may be specified either by calling (setf background-color) or by passing the background-color initarg to make-instance or make-window when creating the object. The value may be either an RGB instance (see make-rgb), nil, or t. nil means to use the default-background-color for the object. t means to use the background color of the parent of the object, if there is a parent, and otherwise use the default-background-color of the object.
The value cannot be an HLS color, as returned by make-hls. If you use HLS colors, apply hls-to-rgb to them before setting this property, and call rgb-to-hls to get the HLS equivalent of an RGB value.
It is typical to leave the background-color of an object nil. In that case, the color returned by default-background-color will be used. If the default methods for that generic function have not been overridden, default-background-color will return a system color such as the one returned by system-background-color or system-dialog-background-color (depending on whether the object is or is not an instance of dialog-mixin). This causes your application to use the end user's preferred colors that they have selected in the Windows Control Panel.
Some widgets that are supplied by the underlying window system will not allow you to change their background color. This is usually true when there is normally no need to use a non-default color.
The actual RGB instance that is passed to (setf background-color) is retained to be returned later by background-color, so an application should not modify an RGB instance while it is assigned to an object. A single RGB instance may be assigned to any number of objects, however.
In earlier releases, this generic function had an optional argument, result-rgb, which was already deprecated and unused. Starting in release 7.0, that argument is no longer supported. Code which includes that argument will signal an error. The error can be fixed by removing any reference to a second, optional argument.
See also with-background-color, a convenient macro that temporarily changes the background color while a body of code is executed.
Generic Function, cg package
Arguments: grid-row-section
Returns (or sets with setf) one of two background colors (see make-rgb) that will be used when drawing the rows of grid-row-section (a grid-row-section). The value may be nil to not specify the color here and instead defer to whatever cell-background-color methods return.
Typically both (or neither) background-color-one and background-color-two are specified, in which case successive rows of the row-section will alternately draw the two colors. This is sometimes called banding.
Generic Function, cg package
Arguments: grid-row-section
Returns (or sets with setf) one of two background colors (see make-rgb) that will be used when drawing the rows of grid-row-section (a grid-row-section). The value may be nil to not specify the color here and instead defer to whatever cell-background-color methods return.
Typically both (or neither) background-color-one and background-color-two are specified, in which case successive rows of the row-section will alternately draw the two colors. This is sometimes called banding.
Generic Function, cg package
Arguments: stream
Returns (or sets with setf) the background-texture of a stream. The background-texture is used by drawing functions that erase an area of a stream, and may be used to "erase" with a pattern rather than a solid color. Functions that use the background-texture of a stream include clear-page, erase-contents-box, erase-contents-circle, erase-contents-circle-sector, erase-contents-ellipse, erase-contents-ellipse-sector, erase-contents-polygon, and erase-contents-rounded-box.
The value should be a pixmap or special symbol, as with fill-texture. See fill-texture for more information and a list of the special symbols.
Generic Function, cg package
Arguments: drag-widget drop-widget position
Called when a drop is done over a control where droppable-p indicates that the drop is not allowed.
The default methods simply display a message in the Allegro CL status-bar in the development environment, and do nothing at runtime.
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the bar-border-colors property of a bar-chart-view. The value may be set at creation time by passing the bar-border-colors initarg, or any time later by calling (setf bar-border-colors).
The colors that are used to draw the borders of the bars of a bar-chart-view in a chart-widget. The value should be a sequence (list or vector) of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list of the symbol black.
If the value is nil, then no borders are drawn on the bars. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.
See also bar-colors.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the bar-chart-view property of a chart-widget. The value may be set at creation time by passing the :bar-chart-view initarg, or any time later by calling (setf bar-chart-view).
bar-chart-view is the chart-view that draws a chart-widget's data as a bar chart. The value is an instance of the bar-chart-view class, and holds properties that are used whenever the chart-view property of the chart-widget is :bar.
The value of this property is always a bar-chart-view instance, even when this view is never used. If you do not pass a bar-chart-view instance as the value of the :bar-chart-view initarg when creating a chart-widget, then a default instance is created automatically.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the bar-colors property of a bar-chart-view. The value may be set at creation time by passing the bar-colors initarg, or any time later by calling (setf bar-colors).
The colors that are used to fill the interior of the bars of a bar-chart-view in a chart-widget. The value should be a sequence (list or vector) of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list returned by the following (the symbols name pre-defined colors, see make-rgb):
(list 'light-blue 'green 'light-red 'yellow
'cyan 'magenta 'blue 'dark-green 'red
'dark-cyan 'dark-yellow 'gray 'dark-gray)If the value is nil, then the bars are not filled and will be transparent. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.
This property and other bar-chart-view properties are used only when the chart-view property of the chart-widget is :bar to display the bar-chart-view.
See also bar-border-colors and bar-fill-textures.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the bar-fill-textures property of a bar-chart-view. The value may be set at creation time by passing the bar-fill-textures initarg, or any time later by calling (setf bar-fill-textures).
The textures that are used to fill the interior of the bars of a bar-chart-view in a chart-widget. The value should be a sequence (list or vector) of values that are valid for the fill-texture property of a graphical-stream (such as arbitrary pixmaps), and/or symbols that are globally bound to such values. The default value is nil.
If the value is nil, then no fill textures will be used and the bars will be filled with solid colors from the bar-colors property. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first texture, the second object with the second texture, and so on. If there are fewer textures in the list than there are chart-objects, then the drawing code will cycle back through the list of textures as needed.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: bar-chart-view
This property has an effect only on the Windows platform.
This property of bar-chart-view determines the value that *color-gradient-blend* will have while filling bars in the bar chart. See *color-gradient-blend* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :bar-gradient-blend initarg to make-instance, or any time later by calling (setf bar-gradient-blend).
Generic Function, cg package
Arguments: bar-chart-view
This property has an effect only on the Windows platform.
This property of bar-chart-view determines the value that *color-gradient-direction* will have while filling bars in the bar chart. See *color-gradient-direction* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :bar-gradient-direction initarg to make-instance, or any time later by calling (setf bar-gradient-direction).
Generic Function, cg package
Arguments: bar-chart-view
This property has an effect only on the Windows platform.
This property of bar-chart-view determines the value that *color-gradient-filling* will have while filling bars in the bar chart. See *color-gradient-filling* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :bar-gradient-filling initarg to make-instance, or any time later by calling (setf bar-gradient-filling).
Generic Function, cg package
Arguments: bar-chart-view
This property has an effect only on the Windows platform.
This property of bar-chart-view determines the value that *color-gradient-intensity* will have while filling bar in the bar chart. See *color-gradient-intensity* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :bar-gradient-intensity initarg to make-instance, or any time later by calling (setf bar-gradient-intensity).
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the bar-spacing property of a bar-chart-view. The value may be set at creation time by passing the bar-spacing initarg, or any time later by calling (setf bar-spacing).
The minimum distance, measured in pixels, between the bars of successive chart items of a bar-chart-view in a chart-widget. The value should be a non-negative integer. The default value is 16.
The actual distance will be greater if needed to prevent tic labels on the item-axis from overlapping each other. See major-label-min-spacing and major-label-wrapping.
When there are multiple side-by-side bars for each chart item (which is when there are multiple chart-objects and the values-are-stacked property is nil), then the side-by-side bars for a single chart item are always adjacent to each other, and this value is the distance between the groups of bars for successive chart items.
If fit-chart-items is true, then this value will be scaled proportionally with other sizing properties to make all data fit in view.
See also bar-width and value-spacing.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: split-bar
Returns the bar-thickness property of a split-bar widget. The value may be set at creation time by passing the :bar-thickness initarg to make-instance, or any time later by call (setf bar-thickness).
This is the actual thickness of the split-bar widget, measured in pixels. It determines the size of the area in which the user can click the mouse to initiate a drag. It should be thick enough to allow the user to easily click on it. The value should be a positive integer. The default value is 9. The value may be set at creation time by passing the :bar-thickness initarg to make-instance, or any time later by call (setf bar-thickness).
The visible bar will be drawn at this thickness when it is not being dragged, unless the draw-at-dragging-thickness property is true. The thickness of the visible bar while dragging is specified with the dragging-thickness property.
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the bar-width property of a bar-chart-view. The value may be set at creation time by passing the bar-width initarg, or any time later by calling (setf bar-width).
The width, measured in pixels, of the bars of a bar-chart-view in a chart-widget. The value should be a positive integer. The default value is 12.
When there are multiple side-by-side bars for each chart item (which is when there are multiple chart-objects and the values-are-stacked property is nil), this is the width of a single bar rather than the width of the group of side-by-side bars.
If fit-chart-items is true, then this value will be scaled proportionally with other sizing properties to make all data fit in view.
See also bar-spacing.
See chart-widget and also .
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the base-line-color property of a bar-chart-view. The value may be set at creation time by passing the base-line-color initarg, or any time later by calling (setf base-line-color).
The color in which a line is drawn at the base-value of a bar-chart-view in a chart-widget. The value should be an RGB object (see make-rgb). The default value is the color returned by (make-rgb :red 140 :green 180 :blue 220).
This property is used only when the base-line-drawn property is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the base-line-drawn property of a bar-chart-view. The value may be set at creation time by passing the base-line-drawn initarg, or any time later by calling (setf base-line-drawn).
A boolean value indicating whether a line is drawn at the base-value of a bar-chart-view in a chart-widget. The default value is nil.
When true, a line is drawn across the body of the chart-widget parallel to the item-axis and at the base-value of the bar-chart-view. The line's thickness will be the base-line-width of the bar-chart-view and its color will be the base-line-color.
If the base-value is equal to the range-bottom or range-top of the value-axis, or if the base-value is outside that range, then the base line is never drawn.
See chart-widget and also .
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the base-line-width property of a bar-chart-view. The value may be set at creation time by passing the base-line-width initarg, or any time later by calling (setf base-line-width).
The thickness, measured in pixels, of a line that is drawn at the base-value of a bar-chart-view in a chart-widget. The value should be a positive integer. The default value is 3.
This property is used only when the base-line-drawn property is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: bar-chart-view
Returns the value of the base-value property of a bar-chart-view. The value may be set at creation time by passing the base-value initarg, or any time later by calling (setf base-value).
The default value for the start of each bar in bar-chart-view in a chart-widget. The value should be a real number. The default value is zero.
Each bar in a bar-chart-view starts at one value on the value-axis and ends at another value. The ending value of a bar is always the main data value for a chart item / chart object pairing that a single bar represents. A "main data value" is the one that is passed as the value argument to set-chart-value or returned from a chart-value-returner function when the value-type argument is :value. The starting value of a bar will be the from-value if one was supplied for the bar, and otherwise it will default to the base-value of the bar-chart-view. The base-value defaults to zero, so every bar by default will start at zero on the value-axis and end at the main value for the bar.
See chart-widget and also .
Generic Function, cg package
Arguments: &optional stream duration
Causes the computer to beep audibly to get the user's attention. The arguments are ignored (they provide backward-compatibility but have no function in the current release).
CG/JS Note: When running in CG/JS mode, the variables *beep-loudness*, *beep-duration*, and *beep-frequency* affect the sound that is produced.
Generic Function, cg package
Arguments: stream
Begins collecting subsequent line-drawing function calls on stream into a "path". Must be followed by a call to end-drawing-path at some point, which actually draws the entire path. stream should be a cg-stream.
A path is useful for filling a collection of lines and curves as a unit.
To ensure that end-drawing-path is always called for each call to begin-drawing-path, it is convenient to use with-drawing-path instead of separate calls to begin-drawing-path and end-drawing-path. See also: line-end, with-line-end, line-join, with-line-join, end-drawing-path, and with-drawing-path.
Generic Function, cg package
Arguments: drawable
Returns the bitmap-stream most recently used by a drawable, or nil if none has been used. This function is not setf'able; the bitmap-stream is created automatically when the use-bitmap-stream property is turned on. Setting use-bitmap-stream to nil disassociates any bitmap-stream from a drawable, although this function will still return the now-unused bitmap-stream.
Thus, if use-bitmap-stream has been turned on and then off, then the leftover bitmap-stream will still be returned. Therefore, an application should not assume that a drawable is currently using a bitmap stream simply because bitmap-stream returns true. Call use-bitmap-stream instead to determine if one is currently being used.
Generic Function, cg package
Arguments: object
Returns the number of bits that are used to represent each pixel of a pixmap or a window. Also known as the depth, the value may be 1, 4, 8, 16, 24, or 32. Depths of 16 bits or greater are known as "true color" because each pixel denotes a color value directly. (Sometimes 16 bits is referred to as "high color" rather than true color because only five bits are available for each of the red, green, and blue color components.) With depths of 8 and less, there are not enough bits to represent a color directly, so each pixel instead denotes an index into a table of colors. For a pixmap, this table is specified by the colors attribute. For a window, the table is specified by assigning a palette to the window, though a depth of 8 (for 256 colors) is generally the only one where the default system colors do not suffice.
Methods exist on pixmap, texture, basic-pane, and screen, though in Windows a single depth is used for the screen and all windows, according to the user's current Control Panel display setting. The depth of a pixmap does not need to match the depth of a window in which it is drawn, though the colors may not be correct when drawn in a window of a lower depth than the pixmap.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the number of milliseconds the argument lamp will stay off when it is blinking (as it does when its value is :blinking).
See the description of the lamp control.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the number of milliseconds the argument lamp will stay on when it is blinking (as it does when its value is :blinking).
See the description of the lamp control.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the body-background-color property of a chart-or-plot. The value may be set at creation time by passing the :body-background-color initarg, or any time later by calling (setf body-background-color).
The background color for the body of a chart-or-plot inside the axes and labels. (The usual background-color property of the widget is used only for the part of the widget outside this area.)
The value is either an RGB object (see make-rgb), or nil to use the widget's default-background-color, or t to use the parent window's background-color. The default value is the value of white.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: grid-widget
Returns (or sets with setf) the background-color-one of the grid-row-section whose name is :body, if there is a row-section named :body in grid-widget (a grid-widget), or else returns nil. See background-color-one for more information.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: grid-widget
Returns (or sets with setf) the background-color-two of the grid-row-section whose name is :body, if there is a row-section named :body in grid-widget (a grid-widget), or else returns nil. See background-color-two for more information.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the body-border-color property of a chart-or-plot. The value may be set at creation time by passing the :body-border-color initarg, or any time later by calling (setf body-border-color).
The color that is used to draw the border lines around the body of a chart-or-plot, inside the labels. The value should be either an RGB object (see make-rgb) or nil to default to the system-edge-shadow-color. The default value is nil.
Any side of the chart body that has an axis will use the axis-color of that chart-axis instead of this color, because the axis stem serves as that part of the chart body border.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the body-border-width property of a chart-or-plot. The value may be set at creation time by passing the :body-border-width initarg, or any time later by calling (setf body-border-width).
The thickness in pixels of the border around the body of a chart-or-plot, inside the labels. The value should be a non-negative integer. Zero means no border is drawn. The default value is 3.
Any side of the chart body that has an axis will use the axis-width of that chart-axis instead of this value, because the axis stem serves as that part of the chart body border.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: grid-widget
Returns the number of columns that are in the grid-column-section whose name is :body, if there is such a section in the column-sections of grid-widget, and otherwise returns 0.
The setf of this function can be called (including at run time) to add or remove columns to that section. If a section named :body does not yet exist, then it is created, placing it just after the section named :header if there is one, or else at the front of all column sections.
See the more general function subsection-count (which this function calls) for more information. See also grid-widget.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: grid-widget
Returns an object that specifies default property values for columns that are in a grid-column-section named :body, if there is such a section in the column-sections of grid-widget (which should be a grid-widget), and otherwise returns nil. See the general function subsection-defaults (which this function calls) for more information.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Typically in the inspector you would go to this object from the grid-widget, and then specify some of the properties for most or all of the main body section of the grid-widget.
There is also footer-column-defaults (which links back to this page saying replace :body with :footer). There is no header-column-defaults as headers normally have only a single subsection.
Generic Function, cg package
Arguments: grid-widget
Returns the list of grid-column objects that are in a grid-column-section named :body, if there is such a section in the column-sections of grid-widget, and otherwise returns nil. The more general function that can be called on any grid-section is subsections.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
A grid-widget that is placed onto a form window will initially have main column and row sections that are named :body, along with header sections that are named :header. When creating a grid-widget programmatically instead, you might want to use those names in custom code as well in order to use convenience functions like this one.
The setf of this function could be called to change the set of columns in the body column section, where any added columns will have properties from the body-column-defaults of grid-widget.
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-blend* will have while drawing the background area of the chart or plot. See *color-gradient-blend* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :body-gradient-blend initarg to make-instance, or any time later by calling (setf body-gradient-blend).
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-direction* will have while drawing the background area of the chart or plot. See *color-gradient-direction* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :body-gradient-direction initarg to make-instance, or any time later by calling (setf body-gradient-direction).
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-filling* will have while drawing the background area of the chart or plot. See *color-gradient-filling* for an explanation of its effect.
The value can be set at creation time by passing the :body-gradient-filling initarg to make-instance, or any time later by calling (setf body-gradient-filling).
To enable gradient filling in chart icons or bars, use icon-gradient-filling or bar-gradient-filling instead.
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-filling* will have while drawing the background area of the chart or plot. See *color-gradient-filling* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :body-gradient-intensity initarg to make-instance, or any time later by calling (setf body-gradient-intensity).
Generic Function, cg package
Arguments: text-edit-pane
Returns the current indentation of the lefthand side of a paragraph of text in a text-edit-pane, or the indentation indicated by the corresponding lower-left slider of a rich-edit-ruler.
This generic function may be called either on a text-edit-pane (typically a rich-edit-pane) or on a rich-edit-ruler. The methods behave somewhat differently: for a text-edit-pane, body-left-indentation is relative to top-left-indentation to match the rich text specification and the Microsoft rich edit control; for a rich-edit-ruler, top-left-indentation is instead relative to body-left-indentation to match the intuitive practice of moving the overall indentation of one or more paragraphs without changing the relative indentation of the first line of each paragraph.
The text-edit-pane method returns the left indentation of the body of the paragraph that contains the text-edit-pane's text cursor (or the first paragraph partly or wholly contained in the selected text, if any). The body is considered to be all lines of the paragraph except the first. This value is measured in points, and is measured rightward from the text-edit-pane's top-left-indentation, which in turn is measured rightward from the interior left of the text-edit-pane. A point is one seventy-second of an inch. Therefore, if a paragraph's body is indented by one inch and its first line is indented by a further inch, the top-left-indentation would be 144 and the body-left-indentation would be -72. This is the way that the rich-edit control was designed in the operating system, and reflects the rich text specification and the values that appear in the rich text string that might be read from the text-edit-pane. For a more intuitive style of measurement, it may be preferable to use the indentation of an associated rich-edit-ruler instead.
The setf method for text-edit-pane sets the indentation of the body of the paragraph that contains the text cursor (or all paragraphs that are partly or wholly selected, if any). If there is a rich-edit-ruler associated with the text-edit-pane (see the function ruler), then the rich-edit-ruler's indentation will be automatically modified to match.
The rich-edit-ruler method returns the position of the slider at the lower left of the ruler, measured in points from the leftmost position. This is not relative to the position of the upper left slider, which is normally used to control the top-left-indentation of a text-edit-pane.
The setf method for rich-edit-ruler moves the lower-left slider of the ruler to the specified position. Since the top-left-indentation of a rich-edit-ruler is relative to the body-left-indentation, the upper-left slider will also move by the same amount. Each slider will be independently constrained at position 0 (the leftmost position) if an attempt is made to move it to a negative position. If there is a text-edit-pane associated with the ruler (see the function rich-edit), then the paragraph in the text-edit-pane that contains the text cursor (or all paragraphs that are partly or wholly contained in the selected text, if any) will be automatically modified to match.
To apply this function to a rich-edit control, first apply window to the control to obtain a rich-edit-pane to pass to this function.
To read or modify multiple paragraph attributes of a text-edit-pane at once, see get-paragraph-format or set-paragraph-format. See also right-indentation.
See cg-rich-text.html for information on rich text editing in Common Graphics.
Generic Function, cg package
Arguments: grid-widget
Returns the number of rows that are in the grid-row-section whose name is :body, if there is such a section in the row-sections of grid-widget, and otherwise returns 0.
The setf of this function can be called (including at run time) to add or remove rows to that section. If a section named :body does not yet exist, then it is created, placing it just after the section named :header if there is one, or else at the front of all row sections.
See the more general function subsection-count (which this function calls) for more information. See also grid-widget.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: grid-widget
Returns an object that specifies default property values for rows that are in a grid-row-section named :body, if there is such a section in the row-sections of grid-widget (which should be a grid-widget), and otherwise returns nil. See the general function subsection-defaults (which this function calls) for more information.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Typically in the inspector you would go to this object from the grid-widget, and then specify some of the properties for most or all of the main body section of the grid-widget.
There is also footer-row-defaults (which links back to this page saying replace :body with :footer). There is no header-row-defaults as headers normally have only a single subsection.
Generic Function, cg package
Arguments: class-grid
Returns the initial section-size of the grid-rows in the body of a class-grid. The value may be set with the body-row-height initarg or by calling (setf body-row-height). Setting the value will changed the section-size of every body row to that size.
Generic Function, cg package
Arguments: grid-widget
Returns the list of grid-row objects that are in a grid-row-section named :body, if there is such a section in the row-sections of grid-widget, and otherwise returns nil. The more general function that can be called on any grid-section is subsections.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
A grid-widget that is placed onto a form window will initially have main column and row sections that are named :body, along with header sections that are named :header. When creating a grid-widget programmatically instead, you might want to use those names in custom code as well in order to use convenience functions like this one.
The setf of this function could be called to change the set of rows in the body row section, where any added rows will have properties from the body-row-defaults of grid-widget.
Generic Function, cg package
Arguments: text-edit-pane
The function returns t if all of the selected range of text-edit-pane is bold, nil if it is all non-bold, and :some if there is a mix.
The setf function turns boldness on or off in the selected range of text-edit-pane. value is either nil to turn it off or true to turn it on.
text-edit-pane must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information on rich text editing in Common Graphics.
Generic Function, cg package
Arguments: cell-style
A boolean property of a cell-style of a calendar widget. When true, the text in the calendar cells for that cell-style will be drawn in bold, and otherwise they will not (unless the font property of the calendar widget is bold itself).
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: window-or-widget
Returns the style of the window-or-widget's border. Various border styles are listed below. Only some styles are appropriate for a specific object.
The border property may not be changed on an existing window or widget, and must instead be specified with the inspector when designing a window or widget (using a form window) or with the :border initarg of make-window or (for a widget) make-instance. (It can be changed using the inspector when designing a form window but not for a running window or widget, either in the IDE or in an application.)
Here are the possible values and their effects:
:frame: use a thick frame that includes a title-bar along the top. The title bar will include buttons for manipulating the window if options to make-window such as :minimize-button are true (as they are by default). Not applicable to widgets.
:dialog-box: similar to :frame, but without minimize and maximize buttons. Not applicable to widgets.
:palette: similar to :dialog-box, but with a shorter title bar that has a somewhat shorter font. The title bar also does not have a system menu button at the left. Typically used for "floating toolbar" windows. Not applicable to widgets.
:black: use a one-pixel-thick black border.
:none: use no border at all.
:none-allowing-title: use no border, but still allow the window to have a title-bar. Otherwise a borderless window will never have a title bar.
:plain: use a standard border and no title bar. This is the default value for various widgets that do not simply display a static value. Typically you do not need to specify the border for a widget, because the default is the appropriate value for that kind of widget.
:static: use a thinner border. This is the default value for various widgets that simply display a static value.
For group-box widgets the border can have the following special properties:
:2d: the border of the group-box is a plain gray line.
:raised: the body of the group-box is raised.
:raised-edge: the border is raised.
:sunken: the body of the group-box is sunken.
:sunken-edge: the border is sunken.
Generic Function, cg package
Arguments: grid-object
Returns the color that will be used to draw border lines in a grid-widget, grid-section, scrolling-static-text, chart-legend, or lamp. The value may be set at creation time by passing the border-color initarg, or any time later by calling (setf border-color).
Specifies the color in which to draw a border line along the right side of a grid-column or grid-column-section, or along the bottom of a grid-row or grid-row-section, or around an entire grid-widget.
The value may be either an RGB color object (as returned by make-rgb or ask-user-for-color), or a symbol whose global value is an RGB object, or nil to use a default color. The value may also be t to to use the system-edge-shadow-color. The default is t for a grid-widget and nil for the others.
When nil, effective-border-color will find the default color to use (except for a grid-widget, where nil will use black).
The value may be nil to draw no border at all, or an RGB color object (see make-rgb) to draw a border in that color, or t to draw a border in the system-edge-shadow-color. The default is nil. See also draw-focus.
Returns the value of the border-color property of a chart-legend. The value may be set at creation time by passing the border-color initarg, or any time later by calling (setf border-color).
The color that is used to draw the rectangular border around the chart-legend of a chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of gray.
This property is used only when the draw-legend and draw-legend-border properties of the chart-legend are both true.
Specifies the color of the lines that are drawn for the perimeter of each lamp image, as opposed to the on-color and off-color that are used to fill the image. (A border is never drawn around the entire widget.) The default is the value of the constant black.
Generic Function, cg package
Arguments: grid-section-any
Returns the border-dashing property of its argument. That property specifies the style of dashed or solid line that will be used for a grid-row or grid-column. The possible values are the same as the possible values of line-dashing.
Generic Function, cg package
Arguments: calendar-widget
The number of blank pixels between a calendar widget's external border and the content inside.
Several pixels are suitable when show-focus-box is true, to avoid the focus box being adjacent to the calendar contents. But if is nil then this property could be zero to minimize the space that the widget occupies.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: grid-object
Returns the width in pixels, if one has been specified, with which to draw a border along the right side of a grid-column or grid-column-section, or along the bottom of a grid-row or grid-row-section, or around an entire grid-widget. The setf of this function may be called to change the width, at which time the grid will be drawn as needed to display the new border width.
The value may be either a non-negative integer or nil. The initial value is nil. When nil, effective-border-width will find a width to use in some other way. Zero means to draw no border at all (though cell-3d-border may still be used to draw a separate 3d border).
An exception to the above rule is that if the object is a grid-widget then nil is not a valid value, the initial value is 3, and effective-border-width is not called.
Generic Function, cg package
Arguments: box
Returns the coefficient of the bottom of box.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the bottom-attachment property of the argument. This property determines which edge of the parent window the bottom edge the object will follow whenever the parent window gets resized. See also top-attachment, left-attachment, and right-attachment.
The possible values and their effects are:
:bottom: object maintains a constant distance between its lower edge and the lower edge of its parent window whenever that window is resized.
:scale: object maintains the same ratio of the distances from the top and bottom sides of its parent window whenever that window is resized. I.e., if the bottom edge was halfway between the top and bottom sides of the dialog before resizing, then it is still halfway between them after resizing.
:top: object maintains a constant distance between its lower edge and the upper edge of its parent window whenever that window is resized.
A control that drops a list of choices when clicked (namely a combo-box or dropping-outline control) always has the same height when not showing its dropping list, and so bottom-attachment for these controls applies to the bottom of the dropped list of choices instead. To keep the dropping list the same height as the user resizes the parent window, bottom-attachment should be the same as the top-attachment. (When both attachments are :scale, a control normally resizes proportionally as its parent window is resized; a dropping list is an exception since it is typically more desirable for the list to continue to show the same number of items than it is to prevent it from overlapping other controls.)
See also top-attachment, left-attachment, right-attachment, track-limits and resize-window.
Generic Function, cg package
Arguments: graphical-stream &optional (stream-units-p t)
Returns the current bottom margin of a graphical-stream, measured from the top edge of the stream. The bottom-margin is initially the page-height of the stream, except as noted below. (setf bottom-margin) may be called to set the margin at any time.
If stream-units-p is true, as it is by default, then the margin is measured in pixels. If nil, it is measured in text line heights (see line-height.
Margin attributes are provided primarily to allow an application to keep a drawing within arbitrary margins by drawing everything within the coordinates returned by left-margin, top-margin, right-margin, and bottom-margin, Common Graphics also uses them in a few special ways, though, as described below.
When drawing on a printer stream, typically an application should check whether the next thing that it is about to draw would extend past the bottom-margin. If so, then it should call new-page to tell the printer to move to a new sheet of paper, and then proceed to draw on the new page. The call to new-page will set the current-position-x of the stream to its left-margin and the current-position-y of the stream to its top-margin, so that text output will continue from the top of the new page. For other drawing functions, the application should adjust the coordinates at which it is drawing, generally by subtracting the page-length of the stream. The page-length is equal to the stream's top-margin subtracted from its bottom-margin.
A printer stream's coordinate system has position (0, 0) at the printer-physical-offset of the printer. To allow an application to avoid dealing with this arbitrary offset, Common Graphics sets the margins of a printer stream to the distance from the physical offset to the margins selected by the user in the print job dialog or page setup dialog. This allows the application to maintain the requested paper margins by simply drawing everything within the four margins that were set up automatically. See *default-printer-left-margin* for more information.
Generic Function, cg package
Arguments: object
Returns a box object that specifies the exterior of the argument object with respect to its parent. The object may be a dialog-item, or window (though box simply calls exterior when passed a non-widget window). (setf box) may be called to resize the object.
When passed a combo-box or dropping-outline dialog-item (or the dialog-item's window), the returned box includes the height of the dropping pane of the widget. Similarly, when calling (setf box), the height should specify the height of the widget with its dropping pane; this determines how far the dropping pane can extend downward. (The undropped widget is maintained at a standard height.) To instead find the box that does not include the dropping pane, use (exterior (window dialog-item)) (see exterior and window).
Beginning in version 7.0, the box method specializing on hotspot has become the new generic function hotspot-region, though the box method for hotspots and its associated :box initarg still exist for compatibility.
Function, cg package
Arguments: box
Returns the bottom of box. This function is setf'able. Thus:
;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position that is the center of the bottom of box rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position that is the bottom left corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position that is the bottom right corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is NIL, a new position object is returned.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position that is the center of box, rounding down where necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
function, cg package
Arguments: box
Returns an integer for the horizontal middle of the specified box. The argument should be a box; see make-box.
function, cg package
Arguments: box
Returns an integer for the vertical middle of the specified box. The argument should be a box; see make-box.
Function, cg package
Arguments: box
Returns the height of box.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box1 box2 &optional box-to-return
Returns the box which is the intersection of the arguments, or nil if they do not intersect. If box-to-return is specified and non-nil, it must be a box object (see make-box. If that case, box-to-return will be modified to be the intersection, if box-intersect returns non-nil. (This will save space by avoiding the creation of a new box object.) If box-to-return is unspecified or specified nil, a new box is created if the arguments intersect.
Boxes which touch just on their edges or at the vertices are not considered to intersect. Thus,
(make-box 10 10 20 20)does not intersect
(make-box 20 20 30 30)but does intersect
(make-box 19 19 30 30)See the description of the box class for general information on boxes.
Function, cg package
Arguments: box1 box2
Returns true if the argument boxes intersect and returns nil if they do not intersect. Boxes which touch just on their edges or at the vertices are not considered to intersect. Thus,
(make-box 10 10 20 20)does not intersect
(make-box 20 20 30 30)but does intersect
(make-box 19 19 30 30)See the description of the box class for general information on boxes.
Function, cg package
Arguments: box
Returns the coordinate of the left edge of box. This function is setf'able. Thus:
;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position which is the center of the left edge of box, rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box offset
Returns a new box object created from box and offset as follows:
(make-box (+ (box-left box) (position-x offset))
(+ (box-top box) (position-y offset))
(+ (box-right box) (position-x offset))
(+ (box-bottom box) (position-y offset))) See make-box and the description of the box class for general information on boxes. See also nbox-move, which modifies its box argument rather than creating a new box object.
Function, cg package
Arguments: box
Returns the coordinate of the right edge of box. This function is setf'able. Thus:
;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position of the right center of box, rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
Generic Function, cg package
Arguments: dialog-item
Should return a box indicating the section of the control's image that should be dragged along with the mouse cursor during a drag-and-drop gesture (see drag-and-drop). The box should be relative to the upper left corner of the scrollable contents of the control.
Methods are supplied for most controls to return the area occupied by the currently selected value of the control.
This image is used only if
(drag-images (configuration *system*))has been set to true. It is nil by default. (See drag-images, configuration, and *system*.)
Function, cg package
Arguments: box
Returns the coordinate of the top of box. This function is setf'able. Thus:
;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position that is the center of the top of box, rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position that is the top left corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box &optional position-to-return
Returns the position that is the top right corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box1 &rest boxes
Returns a box that is the union of box1 and the other argument boxes. The union of several boxes is the smallest box that contains them all.
See the description of the box class for general information on boxes.
Function, cg package
Arguments: box
Returns the width of box.
See the description of the box class for general information on boxes.
Generic Function, cg package
Arguments: object
Returns t if the argument is a box object and returns nil otherwise.
See the description of the make-box for more information on boxes.
boxp should not be called on objects created by the macros with-boxes and with-positions-and-boxes. The return value of those functions is undefined for objects created by the macros because type information for such objects is sacrificed to achieve the non-consing efficiency of stack allocation.
Function, cg package
Arguments: box1 box2
Returns true if box1 and box2 are boxes with the same location and dimensions (they need not be the same Lisp objects). Returns nil if box1 and box2 are different.
See the description of the box class for general information on boxes.
Generic Function, cg package
This function has been removed in the 7.0 release. In earlier releases, it returned the brief comtab that was used internally in the IDE editor. The IDE configuration option ide:editor-mode (with its widget on the Editor tab of the Options) is the exported way to select which comtab the editor uses. The code called by these comtabs exists mostly in the IDE only, and so these comtabs were not useful for applications.
Generic Function, cg package
Arguments: window &key recurse
Brings window in front of all of its sibling windows, if it is not already in front. If recurse is true, then the same thing is done to each of window's ancestor windows, which guarantees that window will not remain behind any window in the whole window hierarchy. See also select-window, which brings a window to the front and selects it.
If you are running a multi-threaded Common Graphics application in Windows desktop mode, see set-foreground-window, because this function (and select-window) may not reliably move a top-level window in front of windows that were created by other threads.
Generic Function, cg package
Arguments: up-down-control
Returns the side of a buddy-widget to which the up-down-control is attached. See up-down-control.
The buddy-side property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :buddy-side initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
buddy-side is a property of the up-down-control class.
Generic Function, cg package
Arguments: up-down-control
Returns the name of the control to which the argument up-down-control, which must be an up-down-control, is attached. That control is called the buddy-widget. A typical buddy widget is an editable-text control with a numeric value. The value can be increased or decreased with the up-down control (as well as typing directly into the text control).
See also the generic function up-down-control.
When designing a form with the IDE, a buddy-widget is connected to an up-down control by clicking on the up-down-control, dragging it over the desired buddy, and dropping it over either the left or the right side of the buddy. A buddy control may be programmatically connected by passing the name of the desired editable-text control as the value of the :buddy-widget initarg when creating the up-down-control, and by passing the name of the up-down-control as the value of the :up-down-control initarg when creating the editable-text control.
Here are the possible values and their effects:
nil: the up-down-control is not connected to another control.
another-control-name (some editable-text-box): for any editable-text control with a companion up-down-control, the value of the buddy-widget property for that up-down-control is the name of that editable-text control.
buddy-widget is a property of the up-down-control class.
Generic Function, cg package
Arguments: project-or-app
Returns an integer that indicates how many times the standalone application for a project has been built. This information could be presented in an About dialog, for example, to distinguish between builds.
This project property is automatically incremented each time the File | Build Project Distribution command is used to generate the standalone app, and the setf of this function could be used to set the value arbitrarily (though it should always be a non-negative integer). The build-number of a new project will be zero, and the first build will be build number 1.
In the standalone application (as well as in the IDE), build-number is also a property of the app object, where it can be retrieved with the expression (build-number (app *system*)), since the project itself is not present in the generated app.
If you build projects programmatically by calling build-project, then you could avoid incrementing the build-number of the project by passing the increment-build-number argument as nil. That would avoid modifying the project and making the IDE inclined to save it.
Generic Function, cg package
Arguments: widget
Moves widget to the bottom of the occlusion stack, so that it will appear behind any overlapping controls. Further, widget is placed last in the tab order for the dialog.
Function, cg package
Arguments: window
Moves window to the bottom of the occlusion stack, so that it will appear behind any overlapping sibling windows.
Generic Function, cg package
Arguments: multi-picture-button
Returns (or sets with setf) the value of the button-3d-border property of a multi-picture-button. This value determines what kind of border with a three-dimensional appearance (if any) will be drawn around each button of the widget. Here are the valid values:
nil: no borders with a three-dimensional appearance are drawn.
t: a thin border with a three-dimensional appearance is drawn around each button.
:when-pressed: a thin border with a three-dimensional appearance is drawn around each button whenever the button is in a pressed-down state or when the mouse cursor is over the button. At other times no border is drawn. This style also draws a separator bar between buttons wherever there is a :gap in the range (see the description of the range property in the description of multi-picture-button).
:thick: a thicker border is drawn around each button.
The 3d border is independent of the button-black-border, which is drawn around the 3d border if both are specified. The borders are drawn around the padding of each button but not around the spacing between the buttons.
Generic Function, cg package
Arguments: multi-picture-button
Returns (or sets with setf) the value of the button-black-border property of multi-picture-button. This value determines whether a thin black border is drawn around each button of the control.
The black border is independent of the button-3d-border, which is drawn inside the black border if both are specified. The borders are drawn around the padding of each button but not around the spacing between the buttons.
button-black-border is a property of the multi-picture-button class.
Generic Function, cg package
Arguments: static-text-and-button-column-mixin
Returns (or sets with setf) whether the buttons in the specified grid-column fill their cells or are small buttons in the lower right corners of the cells.
If the value of this static-text-and-button-column-mixin property is true, then the button in each widget-row-mixin cell of this column will fill the entire cell (within the cell's cell-vertical-padding and cell-horizontal-padding), and the cell's text will be drawn inside the button. If nil, then the button will be small and located in the lower right corner, with the text printed to the left of the button.
The default value is nil for backward compatibility, though true may be a more aesthetically pleasing choice, and may fit more text into the cell. The name static-text-and-button-column-mixin to which this property applies is not quite accurate when this option is turned on, but has been kept for compatibility as well.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: static-text-and-button-column-mixin-instance
Returns the name of a function that will be run when the small button in a grid-column of class static-text-and-button-column-mixin (in a grid-widget) is pressed. A button-function may also be nil instead of a function, in which case the button will do nothing. The default is nil.
A button-function should take six arguments: (1) the grid-widget, (2) the data-object of the grid-row that the clicked cell is in, (3) the grid-row, (4) the grid-column, (5) the row number, and (6) the column number. In releases before 8.0, the function took four arguments (the first four listed) and four arguments will still work but code should be changed to use six arguments. Defining the arguments as optional will allow correct code in both 8.0 and earlier releases.
Generic Function, cg package
Arguments: object
Returns true if the argument is an instance of the button-info class and returns nil otherwise.
Macro, cg package
Arguments: button-state button-form
Compares the button-state to the buttons described in button-form. button-form is recursively defined as follows:
simple-button-form |
(only simple-button-form) |
(not button-form) |
(or button-form*) |
(and button-form*) |
NONE |
nil |
UPWhere simple-button-form can be any constant with an integer value. Examples of button-forms are:
meta-key
(only shift-key)
(and (or shift-key meta-key) (not left-mouse-button))Function, cg package
This function is no longer supported. typep instead.
Function, cg package
Arguments: button-widget new-value old-value
A function that can be used as the on-change event-handler for a button component when the only desired action of the button is to return from a modal dialog invocation, returning the button component itself from pop-up-modal-dialog.
Generic Function, cg package
Arguments: common-control
Returns the value of the button-style property of its argument. This property determines whether headers look like buttons (value t) or not (value nil).
The button-style property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :button-style initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
button-style is a property of the header-control and tab-control classes.
Generic Function, cg package
Arguments: grid-widget
Caches the values for all cells of grid-widget that are not cached already. Also calls invalidate on grid-widget to cause it to be redrawn with possibly updated application values. This function should be called only on a grid-widget whose cache-cell-values property is true. See that property for more information.
To ensure that all cached values are up-to-date, call clear-cached-cell-values just before calling this function.
If reading cell values takes significant time, then calling this function may cause an initial delay as all cell values are read and cached, but may make scrolling faster by avoiding reading and caching values when they are first scrolled into view later. For a very large grid, the space to store all of the cached values may be significant.
Using this function can also prevent cell values from being read at unpredictable redisplay times, when it might not be safe. For example, if a read-cell-value method is reading from a remote database (this includes when the data-object of a grid row is a remote database object), then a redisplay at an unpredictable time could attempt to read its value while other code is already reading it. Calling this function at a known safe time will cache values so that they will not get read at redisplay time.
Generic Function, cg package
Arguments: grid-widget
Returns whether grid-widget (which must be a grid-widget) will cache cell values that it reads, to minimize the number of calls to application code that returns data to display. The value may be set at creation time by passing the cache-cell-values initarg, or any time later by calling (setf cache-cell-values). The default value is nil.
If nil, then application code is called every time a grid cell is drawn, to find the value to display in that cell. This involves calling read-cell-value methods or data-reader functions that are supplied by the application. If this code takes significant time, then it can slow down the drawing of a grid-widget. This may be especially noticeable during smooth scrolling. The application code can also be called many times when sort-grid is called.
If true, then a read-cell-value:around method will cache the value that is read for a cell the first time the cell is drawn, and then use the cached value any time the cell is redrawn thereafter. This continues until the application either calls clear-cached-cell-value for that cell, or calls clear-cached-cell-values to uncache the values for all cells of the grid-widget. To read and cache the values of all cells at once (rather than waiting until if and when they get displayed), call cache-all-cell-values.
Function, cg package
Arguments: cursor
Stores cursor into a global list of stored cursors, so that it can later be found from its name by calling find-cursor. Similar to cache-pixmap for pixmaps. See also uncache-cursor.
All of the built-in mouse cursors are always cached, so this function is needed only when defining a custom mouse cursor, which is possible only in Windows desktop mode. See the section on mouse cursors in cg-pixmaps.html.
Generic Function, cg package
Arguments: pixmap
Stores pixmap internally so that it can later be retrieved by calling find-pixmap on its name.
Generic Function, cg package
Arguments: calendar-widget
Returns an integer (1 to 31) for the date of the universal time that is currently the value property of a calendar widget.
See also the cell-style class and the calendar class.
Generic Function, cg package
Arguments: calendar-widget
Returns an integer (0 to 6, where 0 means Monday) for the weekday of the universal time that is currently the value property of a calendar widget.
See also the cell-style class and the calendar class.
Generic Function, cg package
Arguments: calendar-widget
The type of date range that a calendar widget is currently displaying. The value should be one of the keyword symbols :month, :year, :decade, or :century. The value may be set to switch the mode programmatically, though typically the user switches it interactively after the calendar is initially displayed in :month mode.
See also the cell-style class and the calendar class.
Generic Function, cg package
Arguments: calendar-widget
Returns an integer (1 to 12) for the month of the universal time that is currently the value property of a calendar widget.
See also the cell-style class and the calendar class.
Generic Function, cg package
Arguments: calendar-widget
The font to use for the title of a calendar widget. The value nil means to use the same font as the body, from the font property.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: calendar-widget
Returns an integer for the year of the universal time that is currently the value property of a calendar widget.
See also the cell-style class and the calendar class.
Function, cg package
Arguments: alist module &key reply-needed read-reply-from-string even-when-exiting
Calls a function in custom JavaScript code that's running in a web browser for a CG/JS application, after import-javascript-file was called at run time to load the JS file. The possibilities for this function are not described completely here, but this may be enough for making basic calls into JavaScript.
The alist argument will be described last, because its entry is long.
The module argument is the pathname-name of the JavaScript file that was loaded by calling import-javascript-file. This is used for cleanly separating the namespaces of multiple JavaScript files that might get imported and the namespace of the internal JS code of CG. It also fits well with the way that the JavaScript import function works.
If reply-needed is true, then call-js will not return until the JS function that was called returns, and the internal JS code of CG then sends a reply to Lisp. call-js will then receive as a string whatever the JS function returned, and will return that string. If you would like to return a set of values, then your JS code could call encodeLispArgs (a CG function) on a JS array of values, and then Lisp will receive a string that the Lisp reader would read as a Lisp list.
If read-reply-from-string is true, then call-js will call read-from-string inside an error handler on the string that was received from the web browser, and then return either the value that was read or nil if an errored was signaled. If your JavaScript code called encodeLispArgs on a JS vector to derive the string to return, then this should result in call-js returning a Lisp list.
If even-when-exiting is true, then call-js will make the call even if Lisp has begun the process of exiting. Otherwise it will not make the call because that might interfere with Lisp exit, and so it will immediately return nil. In no case will it attempt the call if it is known that the web browser has disconnected, such as by the user closing the browser tab.
The main alist argument is an association list that contains entries for the name of the function that's being called and the arguments to pass to it. For example, this code snippet emulates how the CG function move-window tells the JS code to do the move:
(call-js
`((fun "moveWindow")
(args ,(list (handle window)
(position-x position)(position-y position))))
"one") ;; the pathname-name of the JS file that was importedThat calls a JavaScript function that looks like this:
function moveWindow (handle, x, y) {
var frame = windows[handle];
var fstyle = frame.style;
fstyle.left = x + "px";
fstyle.top = y + "px";
}You generally should not call built-in CG functions like that one, because CG (in Lisp) would not be aware of that and may get confused. But you can call your own JavaScript code in a similar way, and you could even import a file named "one.js" that exports its own function named moveWindow and call it as in that example.
CG internally uses that form of the alist argument for almost all of its calls, where the alist has a "fun" entry with the name of the JavaScript function to call, followed by an "args" entry with the arguments to pass. The alist keywords like "fun" and "args" are symbols, but the package of the symbols that you use does not matter because only their string names are passed to JS.
An alternate format for calling call-js uses individual named arguments in the association list instead of a single "args" argument. This is similar to passing keyword arguments in Lisp. If the moveWindow example were written that way, then the Lisp code might look like this, with argument names as alist keys:
(call-js `((fun "moveWindow")
(handle ,(handle window))
(x ,(position-x position))
(y ,(position-y position)))
"one") ;; the pathname-name of the JS fileThen the JavaScript function would be called with a single JS object whose property names are those alist keys, and JS code can extract the individual values from that object by name:
function moveWindow (args) {
var frame = windows[args.handle];
var fstyle = frame.style;
fstyle.left = args.x + "px";
fstyle.top = args.y + "px";
}Those examples show how CG passes a window to JavaScript by sending its handle, which in CG/JS is an integer. This is done because Lisp objects would make no sense in JavaScript, of course. Then the JS code finds its HTML element for the window by using that integer as an index in a global "windows" vector that maps window handles to the HTML elements that serve as windows in the web browser. A JS vector works because the window handles are sequential positive integers beginning with 1, while zero is reserved for the screen. So windows[1] in the JavaScript code will return the first window that was created, while windows[0] will return the element that acts as the logical screen for the CG/JS app. (Or you could use the variable cgScreen, which holds the CG screen element.)
If you want your JS code to use windows that were created by CG, then you may need to do something like adding a layer of functions that accept a CG handle, then find the CG window element for the handle, and pass that to one of your existing functions. Something like this:
function doSomethingFromCG (cgWindowHandle) {
doSomething(windows[cgWindowHandle]);
}
function doSomething (htmlElement) {
... }If you instead want to pass references to HTML elements that your JS code has created, then you could for example pass the HTML id attribute of the element instead of a CG window handle, and then find the HTML element itself in your JS code by calling document.getElementById as usual. Or use document.querySelector from scratch in your JS code.
One paradigm that may be useful is using an existing JS function that draws content to draw that content in a CG window. This would need to deal with the design where any regular CG window has an outer parent HTML element for the CG border and title bar, which has a child element for the interior of the window, and that child has a child that's a JS canvas for drawing on. CG stores the interior of a parent in an interior attribute, and the canvas of the interior element in a canvas attribute. So a custom JS function for drawing something in a CG window could begin like this to find the context for passing to JS drawing functions:
function drawMyDiagram (cgWindowHandle) {
let canvas = windows[cgWindowHandle].interior.canvas;
let ctx = canvas.getContext("2d");Some types of Lisp values get converted automatically as needed for passing to JavaScript. The symbol nil will be passed as the JavaScript value false, while t will be passed as true. Other symbols will be passed as their symbol name strings, with no package qualifier. Numbers will be passed as numbers. A CG rgb color object (as created with make-rgb) will be passed as a JS RGBA color string like "#64ffc8ff". Any non-empty Lisp list will be passed as a JavaScript array, and elements of a list will be converted in a similar way (but only a single level down).
Another paradigm might involve calling existing JS code that creates its own HTML elements, but placing the top-level element into a CG window or onto the logical CG screen. That would allow mixing trees of custom JS elements with trees of CG windows, though it's less obvious what typical use cases may be.
As a final more complete example, here is code from a trivial sample project that demonstrates the two paradigms mentioned above. First, here is the JavaScript code, which exports a drawCheckerBoard function to draw a checker board in random colors inside a CG window, and a newElement function that creates a custom HTML element in a CG window or on the CG screen:
function drawCheckerBoard (handle) {
let canvas = windows[handle].interior.canvas;
let ctx = canvas.getContext("2d");
let count = 8, size = 40, color, useFirstColor = true;
let colorOne = randomColor(), colorTwo = randomColor();
for (let x = 0; x < count; x++) {
for (let y = 0; y < count; y++) {
if (y > 0) useFirstColor = !useFirstColor;
color = useFirstColor ? colorOne : colorTwo;
ctx.fillStyle = color;
ctx.fillRect(x * size, y * size, size, size);
} } }
function newElement (handle, left, top, width, height) {
let parent = windows[handle];
parent = parent.interior || parent;
let element = document.createElement("div");
let previousElement = parent.currentElement;
if (parent.currentElement) parent.removeChild(previousElement);
parent.currentElement = element;
let style = element.style;
let borderColor = randomColor(), borderWidth = 4, padding = 8;
let interiorDecrement = 2 * (borderWidth + padding);
style.display = "block"; style.position = "absolute";
style.padding = padding + "px"; style.borderRadius = "16px";
style.background = "#bbddeecc";
style.left = left + "px"; style.top = top + "px";
style.width = width - interiorDecrement + "px";
style.height = height - interiorDecrement + "px";
style.border = borderWidth + "px solid " + borderColor;
element.innerText = "This border color is " + borderColor + ".";
element.fontSize = 14;
style.fontSize = element.fontSize + "px";
element.onmousedown = function () {
this.fontSize += 1; // increase the font size when clicked
this.style.fontSize = this.fontSize + "px";
}
parent.appendChild(element);
}
function randomColor () {
return "rgb(" + random(256) + "," +
random(256) + "," + random(256) + ")";
}
function random (integer) {
return Math.floor(integer * Math.random())
}
export { drawCheckerBoard, newElement };Second, here is the associated Lisp code. This is the on-change functions of three button widgets on a dialog in a test project, where the first function draws a checker board, the second creates an HTML element in the dialog, and the third creates an HTML element on the CG screen. You could try this out by adding a form window to a new project, placing three button widgets in the upper-right area of the form window, and giving the button widgets these on-change functions. Also add a file named one.js to the project folder and put the JS code above into that file, and enter ("one.js") in the JavaScript Files to import widget on the CG/JS tab of the Project Manager dialog. Then run the project and generate the standalone app!
(defun draw-button-on-change (widget new-value old-value)
(declare (ignorable widget new-value old-value))
(call-js `((fun "drawCheckerBoard")
(args ,(list (handle (parent widget)))))
"one") ;; the pathname-name of the JS file
t)
(defun new-sibling-button-on-change (widget new-value old-value)
(declare (ignore new-value old-value))
(new-element (handle (parent widget))
(left widget)
(+ (bottom (find-sibling :top-level widget)) 24)
(width widget)(width widget))
t)
(defun new-top-level-on-change (widget new-value old-value)
(declare (ignore widget new-value old-value))
(new-element 0 ;; the screen's handle is always zero
60 60 200 200)
t)
(defun new-element (parent-handle left top width height)
(call-js `((fun "newElement")
(args ,(list parent-handle left top width height)))
"one")
t)Generic Function, cg package
Arguments: window clipboard-format
the use of this function is deprecated as it does not in fact seem useful. Common Graphics never calls this overridable generic function internally. Applications that call it should instead keep track of which of its windows know how to paste the various data formats.
Returns true if (a) window knows how to paste an object of type clipboard-format and (b) a value for clipboard-format is currently available on the Windows clipboard (see available-clipboard-formats).
clipboard-format may be one of (:text :rich-text :pixmap).
See cg-rich-text.html for information on rich text editing in Common Graphics. See also cg-clipboard.html.
Generic Function, cg package
Arguments: dialog
If dialog has a cancel-button, it is returned by this function. nil is returned if dialog has no cancel-button. (Placing multiple cancel-buttons on a dialog is possible but not recommended. If a dialog has multiple cancel buttons, only one is returned by this function, but which one is returned cannot be determined.) See the description of the cancel-button class.
Function, cg package
Arguments: object
Returns the print name of its argument (i.e. a string that is the printed representation of the object). If the argument is a symbol, the string is capitalized as if with string-capitalize. No changes are made to the string if the argument is not a symbol.
Function, cg package
Arguments: object
Returns the print name of its argument (i.e. a string that is the printed representation of the object) after capitalizing the argument as if with string-capitalize.
Function, cg package
Arguments: symbol
Returns the print name of its argument, which must be a symbol, after capitalizing it as if with string-capitalize.
Generic Function, cg package
Arguments: window
Redirects all mouse events to window until released with release-mouse. See also with-mouse-captured.
Generic Function, cg package
Arguments: caret-mixin
Returns the value of the caret of its argument (which must be a window that includes the caret-mixin class). The value may be either the symbol :solid, the symbol :gray, or a monochrome bitmap handle (as returned by aclwin:open-texture). :solid or :gray will produce a simple rectangular caret whose dimensions are determined by the caret-width and caret-height methods.
Carets are specific to Microsoft Windows, and caret code in an application will have no effect in CG/JS mode.
Function, cg package
Arguments:
Returns (and with setf sets) the current caret blink time. The units are milliseconds.
Generic Function, cg package
Arguments: caret-mixin
Returns (or sets with setf) the height in pixels of the caret for the argument (a window with caret-mixin). If the caret is a bitmap, then this value is ignored.
Function, cg package
Arguments: window
Returns the current position for the caret of window. Use setf to programmatically move the caret.
Generic Function, cg package
Arguments: caret-mixin
Returns (or sets with setf) the width in pixels of the caret for the argument (a window with caret-mixin). If the caret is a bitmap, then this value is ignored.
Generic Function, cg package
Arguments: row column
This generic function returns whether the grid cell at the intersection of the specified grid-row and grid-column will be drawn with a pseudo-three-dimensional border. Applications may add cell-3d-border methods to determine which cells (if any) will have a 3d border. This border, if drawn, is in addition to the "regular" border (see border-width and default-cell-border-width).
If the returned value is nil (the default), then no 3d borders will be drawn. If it is the keyword :sunken-edge, then 3d borders will be drawn that appear sunken (making the grid cells appear raised). If it is t, then 3d borders will be drawn that appear raised (making the grid cells appear sunken).
The default method returns the value of the default-cell-3d-border property of the grid-row-section, the grid-column-section, or the grid-widget (in that order) that contains the specified cell, if any of those property values is non-nil, and otherwise it returns nil. (The default value of the default-cell-3d-border property is nil, so nil is returned from this default method if the property has not been specified for any of those objects.)
Function, cg package
Arguments: grid-row grid-column
Returns true if and only if available applied to grid-row, available applied to grid-column, and cell-available appliued to both grid-row and grid-column all return true.
Generic Function, cg package
Arguments: row column
Returns true if this particular cell (as opposed to its row or column) is available. This default method calls the column's available-reader on the row's data-object.
Generic Function, cg package
Arguments: row column
Returns the background-color for the cell specified by row and column. The value can be a color or nil, which means use the grid's background color.
If the value is a color, it must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.
An application can supply cell-background-color methods that return the color to use for cells at the intersection of row and column subclasses. The default method will return a color that was specified by a call to (setf cell-color), if any, or else a color that was specified by background-color-one or background-color-two, if any.
Generic Function, cg package
Arguments: row-section column-section row column row-num column-num &optional data-area-only-p
Returns the interior region (excluding borders) of a grid cell in window coordinates, unclipped.
Generic Function, cg package
Arguments: grid-widget buttons column-section column-section-border-p column column-num column-border-p x row-section row-section-border-p row row-num row-border-p y &optional trigger-key
This generic function is called when a cell in a grid-widget is clicked. cell-click methods allow the user to initiate arbitrary actions by clicking in particular cells. Often the action is to prompt the user in some way for a new value for the clicked cell; a cell-click method may then call write-cell-value to write the new value into the application's domain data.
If a particular grid cell is to respond to mouse clicks, and the click is not handled by one of the built-in grid-column types such as combo-box-column-mixin, then the application must supply a cell-click method for cells of that row and column type.
grid-widget, row-section, column-section, row, and column are the grid, grid sections, and grid subsections that contain the grid cell that was clicked. row-number and column-number are non-negative integers that indicate the sub-row or sub-column that was clicked when the subsection is replicated (due to having a section-count property that is greater than one); zero indicates the first subsection, and these numbers are always zero for non-replicated subsections.
x and y are the clicked position within the cell, where zero, zero indicates the upper left corner of the cell (inside the borders). The various ...-border-p arguments are true if the click was within *grid-border-mouse-slack* of the right or bottom border of the particular section or subsection.
If trigger-key is true, this indicates that an actual mouse click was not done, but rather that a special key was pressed to emulate a mouse click with the keyboard. In particular, cell-click is called when the user presses the ENTER key or the SPACE bar (unless the user is in a special mode such as typing into an editable-text-column-mixin cell). trigger-key is then the integer code of the key that was pressed, and is therefore the value of either vk-return or vk-space.
A cell-click method could respond differently to each of these keys; for example, a combo-box-column-mixin cell will drop its choice list when SPACE is pressed, as if the user clicked on the cell's arrow, but will start a text edit when ENTER is pressed (assuming that the column's typable property is on), as if the user clicked in the text area of the cell.
Generic Function, cg package
Arguments: grid-widget row-name-or-index column-name-or-index &key (row-number 0) (column-number 0) (row-section-name :body) (column-section-name :body)
Returns the background color of a grid-widget cell, or sets the background color of a cell with the setf of this function. The setf function is a more convenient way to specify the background color of an arbitrary cell than writing cell-background-color methods that specialize on custom row and column subclasses.
cell-color calls cell-background-color to find the color to return, which will be the color that was supplied by (setf cell-color) if that function was used to specify a color for this cell and no more specific cell-background-color method for the cell returns a color.
The value that's passed to (setf cell-color) should be an RGB color object, as made with make-rgb. See the similar function cell-value for the valid values of the other arguments.
Generic Function, cg package
Arguments: row column
Returns true if the value in the cell can be dragged from the cell. Returns nil otherwise.
Generic Function, cg package
Arguments: grid-row grid-column
This generic function is called whenever a grid-widget cell is drawn, to determine the font that will be current when draw-cell is called for the cell. A font should be returned to be used for the cell that lies at the intersection of the specified row and column. An application may add cell-font methods to determine the current font for various cells. Call make-font-ex or make-font to make the font to return.
The default method calls the font-reader function of the grid-column on the data-object of the grid-row if both of those properties have been supplied by the application, and otherwise returns the font property of the column if it is non-nil, and otherwise returns the font property of the whole grid-widget.
While a custom draw-cell method could simply call with-font to establish the font on the fly, defining cell-font methods may be needed when built-in draw-cell methods are used. For example, a default grid cell will draw a centered string from the value returned by read-cell-value, without the application supplying a custom draw-cell method. And when using the grid-column mixin classes that supply built-in grid cell widgets, such as editable-text-column-mixin and combo-box-column-mixin, built-in draw-cell methods are always used, and so a custom cell-font method can control the font of the otherwise built-in drawing behavior of those cells.
Generic Function, cg package
Arguments: row column
Returns the foreground-color for the cell specified by row and column. The value must be a color or nil, which means use the grid's foreground color.
If the value is a color, it must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.
Generic Function, cg package
Arguments: grid-row grid-column
The line that is drawn as a border between two grid-rows of a grid-widget is typically drawn in a single color from the left side of the whole grid to the right side. If it is desirable instead to draw the line in different colors where it crosses particular grid-columns, then an application can supply cell-horizontal-border-color methods to specify these colors. An application could also call this function, though there is probably no need to do so.
This generic function is called internally when drawing the cell at the intersection of grid-row and grid-column, to see if the border along the bottom of the cell should be drawn in a different color than the general color of that border (which is returned by effective-border-color). The method may return either an RGB color object in order to use that color (see make-rgb), or nil to default to the border's general color, or t to use the cell's effective-background-color. The default method returns nil.
The special value of t (to draw the border with the cell's background color) will effectively remove the border from the bottom of the cell. This may be useful for making two contiguous cells appear as a single cell (though they will still behave as separate cells when moving the keyboard focus, for example). If it is desired to draw a single picture in the interior of the combined cells, then any graphic that lies across the border between the cells should be drawn in the draw-cell method for each of the cells; this will ensure that the graphic is drawn whenever needed. The employee grid example on the Examples tab of the Navigator dialog contains a fancy example of this, to cover a few tricky small aspects of this advanced technique.
Generic Function, cg package
Arguments: row column
Returns the type of horizontal alignment to use when text is drawn in the grid cell at the intersection of the specified grid-row and grid-column. The value may be :left, :center, or :right. The default method returns the horizontal-justification property of the grid-column.
An application can control this alignment by setting the horizontal-justification property of grid columns and/or by writing cell-horizontal-justification methods.
Generic Function, cg package
Arguments: grid-row grid-column
Returns a non-negative integer indicating the breadth (in pixels) of margins along the left and right sides of a grid cell (specified by the grid-row and grid-column arguments) in a grid-widget to reserve between the cell's border and whatever is drawn in the cell. The built-in draw-cell methods call this function to determine where to draw text in the cell; these built-in draw-cell methods include the ones for the special widget mixin columns such as editable-text-column-mixin, as well as the default draw-cell method that simply draws a string from the object that is returned by read-cell-value and data-read-converter.
The default cell-horizontal-padding method returns 4. An application may supply methods to change the padding for built-in cell types, and also for custom cell types if the associated custom draw-cell methods call this generic function and use the returned values (which is not required).
See also cell-vertical-padding.
Generic Function, cg package
Arguments: grid-widget row-section column-section row column row-number column-number buttons key-code
This generic function is called whenever the user presses a key on the keyboard while a grid-widget has the keyboard focus, except when the pressed key is one that is used in a special reserved way for grid navigation. These exceptions include tab, shift-tab, enter, space, page-down, page-up, home, end, the four arrow keys, and delete. In addition, this generic function is never called while the user is typing into an editable-text-column-mixin cell.
An application may add cell-key-down methods to initiate some action when the user presses particular keys while particular cells have the keyboard focus. Often this action is to prompt the user in some way for a new value for the grid cell, or to automatically insert particular grid values depending on the key that was pressed. The cell-key-down methods may call write-cell-value to update the application's data in some way.
grid-widget, row-section, column-section, row, and column are the grid, grid sections, and grid subsections that contain the grid cell that currently has the keyboard focus. row-number and column-number are non-negative integers that indicate the sub-row or sub-column that has the focus when the subsection is replicated (due to having a section-count property that is greater than one); zero indicates the first subsection, and these numbers are always zero for non-replicated subsections.
buttons is an integer that indicates the mouse buttons and shift keys that are down, and is some logior'ed combination of the values of these bit-flag constants: left-mouse-button, middle-mouse-button, right-mouse-button, first-x-button (see *ignore-mouse-x-buttons*), second-x-button (see *ignore-mouse-x-buttons*), shift-key, control-key, and alt-key.
key-code is an integer indicating the particular key that was pressed. If an alphanumeric character appears on the key, then key-code is the char-int of that character. Otherwise, key-code is the value of one of the character name constants beginning with "vk-".
The value of the constant key-names is a list of all of the "vk-" character names.
Here is the default method, which does nothing:
(defmethod cell-key-down
((grid-widget grid-widget)(row-section grid-row-section)
(column-section grid-column-section)
(row grid-row)(column grid-column)
row-number column-number
buttons key-code)
(declare (ignore row-number column-number buttons key-code))
nil)Generic Function, cg package
Arguments: grid-widget column-section column row-section row
This function is called when the mouse cursor moves over a cell. The default method does nothing.
Generic Function, cg package
Arguments: grid-widget column-section column row-section row
This function is called when the mouse cursor moves out of a cell. The default method does nothing.
Generic Function, cg package
Arguments: row column
Returns true if this particular cell (as opposed to its row or column) on a grid-widget is selected. The default method calls the column's selected-reader on the row's data-object, if those two properties are supplied, and otherwise does nothing. An application may add cell-selected methods to determine the selected state of individual cells. Alternately, set the selected property of whole grid-rows and grid-columns.
Generic Function, cg package
Arguments: grid-row grid-column
Returns the color in which to draw the background of the grid-widget cell at the intersection of the specified grid-row and grid-column if the cell is currently selected (see cell-selected, selected, selectable, and selected-reader). The value should be an RGB color object (see make-rgb).
The default method returns the value returned by system-highlight-background-color, which is a color that the end user has specified in the Windows Control Panel. An application may add cell-selected-background-color methods in order to override the Control Panel defaults for some or all grid cells.
See also cell-selected-foreground-color, cell-unavailable-foreground-color, and cell-background-color.
Generic Function, cg package
Arguments: grid-row grid-column
Returns the color in which to draw the foreground of the grid-widget cell at the intersection of the specified grid-row and grid-column if the cell is currently selected (see cell-selected, selected, selectable, and selected-reader). The value should be an RGB color object (see make-rgb).
The default method returns the value returned by system-highlight-foreground-color, which is a color that the end user has specified in the Windows Control Panel. An application may add cell-selected-foreground-color methods in order to override the Control Panel defaults for some or all grid cells.
See also cell-selected-background-color and cell-foreground-color.
Generic Function, cg package
Arguments: calendar-widget
This property of a calendar widget is a cell-style object that determines how regular cells are drawn.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: calendar-widget
This property of a calendar widget is a cell-style object that determines how today's date is drawn.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: calendar-widget
This property of a calendar widget is a cell-style object that determines how dates in the previous and next months are drawn.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: calendar-widget
This property of a calendar widget is a cell-style object that determines how the currently selected cell is drawn.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: calendar-widget
This property of a calendar widget is a cell-style object that determines how the cell that's currently under the mouse is drawn.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: grid-row grid-column
Returns the color in which to draw the foreground of the grid-widget cell at the intersection of the specified grid-row and grid-column if the cell is currently unavailable (see cell-available, available, available-reader, and cell-and-sections-available).
The default method returns the value returned by system-disabled-color, which is a color that the end user has specified in the Windows Control Panel. An application may add cell-unavailable-foreground-color methods in order to override the Control Panel defaults for some or all grid cells.
The value must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.
Generic Function, cg package
Arguments: grid-widget row-name-or-index column-name-or-index &key (row-number 0) (column-number 0) (row-section-name :body) (column-section-name :body)
Returns the value of a grid-widget cell, or sets the value of a cell with the setf of this function.
This function allows specifying a cell value by passing the names or indexes of the grid rows and columns (and sections), rather than passing the row and column objects as with read-cell-value and write-cell-value. This may be more convenient than finding the objects to pass. cell-value calls read-cell-value after finding the named subsections, and (setf cell-value) calls write-cell-value.
row-name-or-index and column-name-or-index should each be either the symbol that names the row or column or the zero-based index of the row or column within its section. row-number and column-number are the sub-indexes within a replicated subsection.
row-section-name and column-section-name should be the symbols that name the sections that the row and column are in. The default is :body for the typical case where you are accessing a main section whose name is :body, such as with a grid-widget that is created interactively by placing it onto a form window (see cg-grid-widget-simplified-tutorial.html).
Generic Function, cg package
Arguments: grid-row grid-column
The line that is drawn as a border between two grid-columns of a grid-widget is typically drawn in a single color from the top of the whole grid to the bottom. If it is desirable instead to draw the line in different colors where it crosses particular grid-rows, then an application can supply cell-vertical-border-color methods to specify these colors. An application could also call this function, though there is probably no need to do so.
This generic function is called internally when drawing the cell at the intersection of grid-row and grid-column, to see if the border along the right side of the cell should be drawn in a different color than the general color of that border (which is returned by effective-border-color). The method may return either an RGB color object in order to use that color (see make-rgb), or nil to default to the border's general color, or t to use the cell's effective-background-color. The default method returns nil.
The special value of t (to draw the border with the cell's background color) will effectively remove the border from the right side of the cell. This may be useful for making two contiguous cells appear as a single cell (though they will still behave as separate cells when moving the keyboard focus, for example). If it is desired to draw a single picture in the interior of the combined cells, then any graphic that lies across the border between the cells should be drawn in the draw-cell method for each of the cells; this will ensure that the graphic is drawn whenever needed. The employee grid example on the Examples tab of the Navigator dialog contains a fancy example of this, to cover a few tricky small aspects of this advanced technique.
Generic Function, cg package
Arguments: row column
Returns the type of vertical alignment to use when text is drawn in the grid cell at the intersection of the specified grid-row and grid-column. The value may be :top, :center, or :bottom. The default method returns the vertical-justification property of the grid-column.
An application can control this alignment by setting the vertical-justification property of grid columns and/or by writing cell-vertical-justification methods.
Generic Function, cg package
Arguments: grid-row grid-column
Returns a non-negative integer indicating the breadth (in pixels) of margins along the top and bottom sides of a grid cell (specified by the grid-row and grid-column arguments) in a grid-widget to reserve between the cell's border and whatever is drawn in the cell. The built-in draw-cell methods call this function to determine where to draw text in the cell; these built-in draw-cell methods include the ones for the special widget mixin columns such as editable-text-column-mixin, as well as the default draw-cell method that simply draws a string from the object that is returned by read-cell-value and data-read-converter.
The default cell-vertical-padding method returns 2. An application may supply methods to change the padding for built-in cell types, and also for custom cell types if the associated custom draw-cell methods call this generic function and use the returned values (which is not required).
See also cell-horizontal-padding.
Generic Function, cg package
Arguments: grid-row grid-column row-number column-number
Returns a number of values that indicate which of the several built-in cell widgets should appear in particular grid-widget cells, and what attributes those widgets should have. The default method does nothing, so an application must add its own cell-widget methods in order to use the built-in cell widgets with this approach.
An alternative approach is to use the various widget-column-mixin subclasses along with the widget-row-mixin class. That approach is more object-oriented, but also limits the built-in cell widgets to particular columns for each type of widget.
The IDE's Navigator dialog contains a complete example of the cell-widget approach, called Grid-widget: using built-in cell widgets in ARBITRARY cells.
The first value returned from a cell-widget method should be a keyword that indicates which type of widget to use in the cell that is indicated by the arguments to cell-widget. The possible values are :button, :static-text, :editable-text, :check-box, :combo-box, :lamp, and :pixmap. For more information on how each of these widgets works, please refer to the associated widget-column-mixin class shown below (even though these classes are not used at all when writing cell-widget methods):
:button -- static-text-and-button-column-mixin
:check-box -- check-box-column-mixin
:combo-box -- combo-box-column-mixin
:editable-text -- editable-text-column-mixin
:static-text -- static-text-column-mixin
:lamp -- lamp-column-mixin
:pixmap -- pixmap-column-mixin
The rest of the multiple values that a cell-widget method should return supply various attributes of the cell's widget. These values depend on which type of widget is being used. Most of these values correspond to properties of the various widget-column-mixin subclasses, though the cell-widget approach does not use those mixin classes. Since the cell-widget approach has no grid-column object on which to hang these property values, we must return them as multiple values from cell-widget methods instead.
Here are the multiple values that a cell-widget method should return for each type of widget. This list includes links to the corresponding widget-column-mixin properties that they emulate, where applicable, for more information.
For a static-text widget, return these values:
the symbol :static-text
the string to display in the cell, or else nil to defer to the read-cell-value method for the cell.
For a button widget, return these values:
the symbol :button
the name of the function to run when the user presses the button (see button-function)
a boolean value indicating whether the button should fill the cell (see button-fills-cell)
a string or pixmap to draw in the cell, or else nil to defer to the read-cell-value method for the cell
a background color for the button (see make-rgb) or else (more typically) nil to default to the cell-background-color method for the cell
a boolean value indicating whether the pixmap (if the fourth returned value is a pixmap) should stretch to fill the button, rather than being drawn at its canonical size
For a check-box widget, return these values:
the symbol :check-box
a string to display beside the check-box gadget (this value must be a string and not nil); the null string will center the gadget horizontally
a boolean value indicating whether the user must click on the check-box gadget itself, rather than anywhere in the cell, to toggle the value (see click-must-be-on-gadget).
For an editable-text widget, return these values:
the symbol :editable-text
a keyword indicating how type-in is initiated (see edit-start-trigger)
a keyword indicating how type-in is terminated (see edit-end-trigger).
For a combo-box widget, return these values:
the symbol :combo-box
a list of choices to display in the drop-down list (this is like the list that a range-reader function would return, but it must be a non-null list of choices)
a boolean value indicating whether the user may type in a new value, rather than selecting from the list of choices
a boolean value indicating whether to use a "real" combo-box for the list of choices rather than a pop-up-menu (see use-real-combo-box, though that option has been deprecated and so nil should always be returned here)
a boolean value indicating whether the user must click on the drop-down arrow gadget itself, rather than anywhere in the cell, to show the list of choices (see click-must-be-on-gadget)
a keyword indicating how type-in (if allowed) is initiated (see edit-start-trigger)
a keyword indicating how type-in (if allowed) is terminated (see edit-end-trigger).
For a lamp widget, return these values:
the symbol :lamp
a real lamp widget, created as usual with make-instance. Typically this widget will not also be used as a standalone lamp widget on a dialog, though it could be, and it may also be displayed by multiple grid cells, even in multiple grid-widgets.
For a pixmap, return these values:
the symbol :pixmap
an association list that maps application values to pixmap names, as with the pixmap-alist property of a grid-column
a boolean value indicating whether the pixmap should be stretched to fill the grid cell; see the stretching property
a boolean value indicating whether the user is allowed to interactively cycle through the cell's set of pixmaps; see user-modifiable
the name of a function to use for testing whether two application values are equivalent, as with the pixmap-value-test property; this value may be omitted to default it to widget-value-equal
These returned values cover only the properties that are unique to the built-in cell widgets. Other attributes of the cell will still be determined by general grid-widget generic functions such as read-cell-value, write-cell-value, cell-font, cell-background-color, cell-horizontal-justification, and so on. See the grid-widget class for a complete overview.
cell-widget methods may be called frequently, so to avoid generating a lot of garbage it is advisable to return static values rather than values that are newly consed on each call.
There is an example using cell-widget on the Examples tab of the Navigator dialog.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: row column
Returns whether text in the cell will wrap (at word boundaries) to multiple lines of text.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: lamp
Returns the value of the center-all property of a lamp widget. The value may be be specified at creation time with the center-all initarg, or anytime later by calling (setf center-all).
If the center-all property is nil, as it is by default, then the lamp images are positioned by the outer margin properties from the edge of the widget on any sides of the lamp image where there are no labels, leaving the rest of the widget's area for the labels. That may be useful for aligning the lamp images of multiple widgets by simply aligning the widgets themselves, without making sure that the widgets are all the same size. If the center-all property is true, then the lamp images and labels are centered as a unit within the widget's area. That may be especially useful when the lamp is used in a grid-widget cell, to keep the widget centered as the grid-widget cell changes in size. (When there are no label strings, the lamp images are always centered.)
Generic Function, cg package
Arguments: configuration
Returns (or sets with setf) the value of the center-all-modal-dialogs-on-screen configuration property.
This property affects modal dialogs displayed by utility functions such as ask-user-for-choice-from-list. Modal dialogs created by application code can be positioned wherever the application likes before they are shown. But applications do not have a handle on built-in modal dialogs and so cannot specify their positions directly. This property gives some measure of control over the placement of such dialogs.
If the typical conventions allowed by this configuration option are not adequate, the built-in utility dialogs can be positioned however you like by writing a position-utility-dialog method.
The value of this property of the current configuration can be t, nil, or :on-owner, which is the default.
If the value is :on-owner, the dialog is centered on the owner window that the application passes to the various utility dialog functions. Such modal dialogs are displayed by functions like ask-user-for-choice-from-list.
If the value is t (or, indeed, any true value other than :on-owner), modal dialogs are positioned in the center of the screen (absent overriding specification of another location). If the value is nil, modal dialogs are placed near the upper left corner of the owner.
Note that for Common Dialogs (implemented by the operating system and invoked by functions such as ask-user-for-new-pathname), Common Graphics does not know how large the dialogs are and therefore cannot center them; therefore, for Common Dialogs, the :on-owner option behaves like nil to position the dialogs at or near the upper left corner of the owner window.
The current configuration is the value of (configuration *system*). (See configuration and *system*.)
See also position-utility-dialog
function, cg package
Arguments: nodes center-x-reader center-y-reader center-writer width-reader height-reader canvas-left canvas-top canvas-right canvas-bottom &key canvas animate (steps 8) redisplay-function cancel-function
This function modifies the nodes passed in a list as the value of the nodes argument. The return value of this function is not defined.
This utility function might be useful when using the function graph-layout to draw graphs and handle mouse events on them. The arguments (except for steps, defined below) should be the same as the same-named arguments to graph-layout. See that function for more information.
This function will call the center-writer function that is passed to it on each of the nodes so as to center the entire set of nodes within the rectangular region that's defined by canvas-left, canvas-top, canvas-right, and canvas-bottom.
One argument to this function that graph-layout does not have is the steps argument. This is the number of incremental steps at which the redisplay-function will be called to draw the entire graph, along the path between the current node positions and their new centered positions. The default value is 8.
Function, cg package
Arguments: stream width height &optional dialog-units-p
Returns a box (dimensions width and height) centered on the page of stream, relative to the current origin. If dialog-units-p is true, the coordinates are assumed to be in dialog units rather than pixels.
Function, cg package
Arguments: width height &optional dialog-units-p
Returns a box (dimensions width and height) centered on the screen. If dialog-units-p is true, the coordinates are assumed to be in dialog units rather than pixels.
Function, cg package
Arguments: window width height &optional dialog-units-p
Returns a box (dimensions width and height) centered on the window relative to the current origin. If dialog-units-p is true, the coordinates are assumed to be in dialog units rather than pixels.
Function, cg package
Arguments: text-edit-pane
Calls (setf justification) on text-edit-pane (a text-edit-pane) with the value :center. This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.
Generic Function, cg package
Arguments: window
Called by the default position-utility-dialog method to decide which convention to use for positioning a utility dialog. The default method simply returns the value of the center-all-modal-dialogs-on-screen configuration option, which is either nil, t, or :on-owner. An application could add methods on this generic function to override the global configuration default for particular owner windows. The method should still return one of the three possible values of center-all-modal-dialogs-on-screen if the default position-utility-dialog method is used.
function, cg package
Arguments: position width height &key box
Returns a box whose center is at the specified position (see make-position) and which has the specified width and height.
The box argument, if specified, should be either a box (see make-box) or nil. If a box, then that box is modified and returned. Otherwise a new box is created and returned.
function, cg package
Arguments: center-x center-y width height &key box
Returns a box whose center is at the position specified by center-x and center-y, and which has the specified width and height.
The box argument, if specified, should be either a box (see make-box) or nil. If a box, then that box is modified and returned. Otherwise a new box is created and returned.
Generic Function, cg package
Arguments: window &key on-parent return-only width height
Moves a window so that it is centered over the interior of its owner or parent. Returns a box that indicates the new exterior of the window.
window should be an instance of the basic-pane class or one of its subclasses.
If on-parent is true, then the window is centered over its parent, and otherwise it is centered over its owner. The default is nil. (The parent and owner of a window are different only when the window is a top-level owned window, in which case the parent is the screen and the owner is the owner window.)
If return-only is true, then the window is actually not moved at all, but the box to where it would have been moved is still returned. If nil (the default), then the window is moved and its new exterior box is returned.
width and height may each be nil (the default) to use the current width or height of the window, or else a positive integer to indicate a new width or height to which to resize the window while centering it.
See also the :centered argument to make-window and the centered property.
Generic Function, cg package
Arguments: window
Returns whether a window was initially centered over the interior of its owner or parent when it was created.
(setf centered) may be called to change the value, though this is useful only for a form in an IDE project, where it indicates whether the running window that is created from the form will be centered. A centered property appears in the inspector for a form (or other window), where it may be set interactively.
When creating a window programmatically, centering is achieved by passing the :centered argument to make-window.
The value may be either nil (the default) for no centering, :on-parent to center over the parent, or any other true value to center over the owner. (The parent and owner of a window are different only when the window is a top-level owned window, in which case the parent is the screen and the owner is the owner window.)
function, cg package
Arguments:
Returns a boolean value indicating whether some Common Graphics functions are currently checking the validity of their arguments whenever they are called. The setf of this function can be called to turn argument checking on or off.
Common Graphics doesn't do argument checking by default, for efficiency reasons. But you can turn it on for debugging purposes with (setf (cg-argument-checking) t), and turn it back off afterward with (setf (cg-argument-checking) nil).
Even when enabled, this facility will check arguments only in a small subset of all user CG functions. These are mostly low-level functions where invalid arguments may be especially confusing or might even corrupt the Lisp. For example, if you called (setf box-right) on a position object, that would write past the end of the shorter position foreign structure and corrupt memory there, though with this argument-checking facility turned on it would instead signal an informative error.
Function, cg package
Arguments: window &key (confirm t)
This function is called by the :commit-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It simply calls db.ac:commit if the user confirms in a modal dialog, and displays a couple of status-bar messages in the specified window, which would typically be an object-editor. The confirmation dialog is skipped if the confirm argument is passed as nil.
function, cg package
Arguments:
Returns a comtab (command table) that contains a subset of the IDE editor keystrokes when ide:editor-mode is :emacs. This comtab could be given to a text-edit-pane in a Common Graphics application to provide the IDE editor's general text-editing keystrokes that are not specific to the IDE.
See cg-host-comtab for a table of all of the keystrokes that are provided by this comtab as well as that one.
function, cg package
Arguments:
Returns a comtab (command table) that contains a subset of the IDE editor keystrokes when ide:editor-mode is :host. This comtab could be given to a text-edit-pane in a Common Graphics application to provide the IDE editor's general text-editing keystrokes that are not specific to the IDE. Example:
(setf (comtab my-text-edit-pane)(cg-host-comtab))Below is a table of the keystrokes that are defined by this comtab as well as by cg-emacs-comtab. The symbols in the left column are functions, but most of them are not exported from the cg package for general application use (though perhaps they should be). They are listed here simply as command names that also appear in the IDE's Help menu | Shortcut Keys dialog.
For brief descriptions of what each of these functions does, see the documentation for the Shortcut Keys.
| Function | Host Comtab | Emacs Comtab |
| backward-character | --- | Ctrl+B |
| backward-delete-line | Alt+Backspace | --- |
| backward-delete-sexp | Ctrl+Shft+Backspace | --- |
| backward-kill-line | --- | Alt+K |
| backward-kill-sexp | --- | Ctrl+Alt+Backspace |
| backward-kill-word | --- |
Ctrl+Backspace Alt+Backspace Alt+H |
| backward-list | --- | Ctrl+Alt+P |
| backward-sexp |
Ctrl+Alt+Left Alt+Left |
Ctrl+Alt+Left Ctrl+Alt+B |
| backward-up-list | Ctrl+Shft+Up |
Ctrl+Alt+U Ctrl+Alt+Down |
| backward-word | --- |
Alt+B Alt+Left |
| beginning-of-buffer | --- | Alt+Shft+Comma |
| beginning-of-line | --- | Ctrl+A |
| beginning-of-next-definition | Alt+Down Ctrl+Alt+Down |
Ctrl+Alt+Close-Square-Bracket |
| beginning-of-this-or-previous-definition |
Alt+Up Ctrl+Alt+Up |
Ctrl+Alt+Open-Square-Bracket Ctrl+Alt+A |
| capitalize-selection | --- | Alt+C |
| copy-command | Ctrl+C | Alt+W |
| cut-command | Ctrl+X | Ctrl+W |
| delete-horizontal-space | Ctrl+Slash | Ctrl+Slash |
| delete-indentation | --- | Ctrl+6 |
| delete-line | Alt+Delete | --- |
| delete-next-character | --- | Ctrl+D |
| delete-previous-character | Ctrl+H | Ctrl+H |
| delete-sexp | Ctrl+Shft+Delete | --- |
| delete-surrounding-whitespace | Alt+Slash | Alt+Slash |
| down-list | --- | Ctrl+Alt+D |
| downcase-selection | --- | Alt+L |
| end-of-buffer | --- | Alt+Shft+Period |
| end-of-definition | --- | Ctrl+Alt+E |
| end-of-line | --- | Ctrl+E |
| exchange-to-mark-command | Alt+Shft+K |
Ctrl+X Ctrl+X Ctrl+3 |
| forward-character | --- | Ctrl+F |
| forward-list | --- | Ctrl+Alt+N |
| forward-sexp | Alt+Right Ctrl+Alt+Right |
Ctrl+Alt+F Ctrl+Alt+Right |
| forward-up-list | Ctrl+Shft+Down | Ctrl+Alt+) |
| forward-word | --- |
Alt+F Alt+Right |
| illegal-operation | --- |
Ctrl+G Alt+G Ctrl+X Ctrl+G |
| insert-empty-list | Ctrl+Shft+3 | Alt+9 |
| insert-empty-string | Ctrl+Shft+2 | Alt+Shft+2 |
| just-one-space | Ctrl+Alt+Slash | Ctrl+Alt+Slash |
| kill-line | --- | Ctrl+K |
| kill-sexp | --- | Ctrl+Alt+K |
| kill-word | --- | Alt+D |
| mark-command | Alt+Shft+J | Ctrl+2 |
| newline | Ctrl+Return |
Return Ctrl+M Shft+Return |
| newline-and-indent | Return Shift+Return |
Ctrl+J |
| next-line | --- | Ctrl+N |
| next-page | --- | Ctrl+V |
| open-line | --- | Ctrl+O |
| paste-command | Ctrl+V | Ctrl+Y |
| previous-line | --- | Ctrl+P |
| previous-page | --- | Alt+V |
| recenter | Ctrl+Space | Ctrl+L |
| reindent-sexp | --- | Ctrl+Alt+Q |
| reindent-single-line | Tab | Tab |
| select-all | Ctrl+A | Alt+Shft+A |
| select-current-sexp | Ctrl+Shft+Return | Ctrl+Shft+Return |
| select-to-mark-command | Alt+Shft+L | Ctrl+4 |
| transpose-characters | Ctrl+Quote | Ctrl+T |
| transpose-sexp | Alt+Quote | --- |
| undo-command | --- | Ctrl+X Ctrl+U |
| upcase-selection | --- | Alt+U |
Function, cg package
Arguments: option-name
Returns one of the values in *cgjs-client-options*. Calling the setf of this function directly has no effect in the usual scenarios, and there are other facilities for modifying these options.
Generic Function, cg package
Arguments: project
Returns a cgjs-options object that stores CG/JS server options for a project. These are typically set interactively in the CG/JS tab of the Project Manager but this object can be used for reading or setting them programmatically.
Function, cg package
Arguments: option-name
Returns one of the values in *cgjs-server-options*.
Calling the setf of this function directly is not supported. It would likely have no effect because the values have already been used once Lisp has started up, and it might cause unforseen confusion.
Function, cg package
Arguments: whostate function &rest args
This function can be called instead of mp:process-wait whenever windowing events may need to be handled during the wait, and the code might be run in CG/JS mode. It can be called with the same arguments as mp:process-wait, and so existing calls to mp:process-wait can be made to work in CG/JS mode in this situation by simply substituting the name of this function.
When running in Windows desktop mode, this function simply calls mp:process-wait, because that function knows how to how to handle Microsoft Windows events during the wait. When running in CG/JS mode, CG uses a custom loop that both handles CG/JS events and exits when the wait function returns true.
Function, cg package
Arguments: &key (confirm t) window
This function is called by the :rollback-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It calls db.ac:rollback if the user confirms in a modal dialog, and displays a couple of status-bar messages in the specified window if one is passed. The confirmation dialog is skipped if the confirm argument is passed as nil.
It then ensures that any object-editor dialogs and class-grid widgets in the environment are brought up to date, by calling uncache-instances-with-pretty-names with the :all argument, and then calling update-all-class-interface-widgets. It is strongly recommended that any application that uses object-editors and/or class-grids call this function rather than calling db.ac:commit directly, or else to call those two exported functions that cg-rollback calls. Otherwise the interface objects may be left in a broken state.
Function, cg package
Arguments:
Returns a built-in timer that is used internally by Common Graphics for a variety of purposes and which normally is always active (but see use-cg-timer). See cg-timer-interval. See also cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: configuration
The internal built-in timer (returned by cg-timer) uses a preset interval for most tasks. This function returns (or sets with setf) that interval. The initial value of the interval is 500 (milliseconds).
This value could be modified by an application to change the quickness with which Common Graphics does a few things such as generating a mouse-out event when the mouse cursor goes outside of any Lisp window, and the speed with which the IDE reports the current package and tracing/profiling flags at the right side of the IDE menubar window. Smaller values will make these actions faster, but may bog down other processing if too frequent. cg-timer-interval is a property of the configuration class. The current configuration is the value of
(configuration *system*)See cg-timers.html for more information on timers.
Function, cg package
Arguments: string
Changes the case of string as needed to match the case in which symbols are normally read in the *current-case-mode*. Specifically, this will lowercase strings in :case-sensitive-lower mode, uppercase strings in :case-sensitive-upper mode, and (in the case-insensitive modes) just return the string as is.
Generic Function, cg package
Arguments: outline item available
Establishes (by the value of the available argument) whether an outline-item is available to the user, given an outline-item structure.
Generic Function, cg package
Arguments: outline item-value available
Establishes (by the value of the available argument) whether an outline-item is available to the user, given the value of an outline-item.
Generic Function, cg package
Arguments: stream line-number
Returns an integer that's the index of the first character in the line of text that's specified by line-number. An exception is that nil is returned if line-number is equal to or greater than the number-of-text-lines in stream, because there is no character index there.
line-number should be a non-negative integer, with zero indicating the first line of text. stream can be a multi-line-editable-text widget or a text-edit-pane.
See also line-number-from-char.
Function, cg package
Arguments: char &key return-comtab-event
This function takes a Lisp character object as an argument and returns the name of the key that is pressed in order to type that character. This name may be a Lisp character object such as #\A or one of the vk-... constants such as vk-period. A second returned value is an integer which is a logior'ed value indicating which shift keys are used with the returned key in order to type the character; the logior'ed values are the values of the symbols shift-key, control-key, and alt-key (whichever of those keys are down).
> (char-to-key-name #\*)
#\8
4 (4 is the value of shift-key)
> (char-to-key-name #\>)
vk-period
4If the keyword argument return-comtab-event is true, then instead of the two returned values detailed above a single value is returned. This value is an event-synonym specifier list in the format that is passed to set-event-function or the :event-synonym initarg of a menu-item.
> (char-to-key-name #\* :return-comtab-event t)
(shift-key #\8)
> (char-to-key-name #\> :return-comtab-event t)
(shift-key vk-period)The association of shifted special characters with unshifted characters is more or less standard on all United States keyboards but can be different (from the US standard) on non-US keyboards. This function may be needed for applications that must work on such non-US-standard keyboards.
Generic Function, cg package
Arguments: window &optional scratch-character-format
The function returns a character-format instance representing the character format of the selected text, if any, and otherwise of the character just before the current text cursor position in window. If scratch-character-format is supplied, it should be a character-format instance which is then filled in and returned. Note that using scratch-character-format avoids consing a new character-format instance.
The setf function sets the character formatting of the currently selected text of window to reflect character-format, which should be a character-format instance.
See cg-rich-text.html for information on rich text editing in Common Graphics. See also get-character-format, which returns the attributes as multiple values rather than as a character-format object. See also get-character-format, which returns the attributes as multiple values rather than as a character-format object.
Function, cg package
Arguments: text-edit-pane position
Returns the zero-based index of the character at position in text-edit-pane if that pixel position is currently scrolled into view, and otherwise returns nil. If there is no character at the specified position (but that position is scrolled into view), then the index of the nearest character is returned.
text-edit-pane should be a text-edit-pane or rich-edit-pane.
position should be a position object (see make-position) in stream coordinates, meaning that it is measured from the upper-left corner of the scrollable contents of the window, and so the value is not affected by the current scroll-position of the window.
(The functionality that is exported by the Windows rich-edit control, which we use for all text-edit-panes in Windows, does not appear to provide a way to determine the character when it is not scrolled into view. There is also no way to programmatically scroll this control to an arbitrary pixel position (in version 1.0), though set-first-visible-line will scroll a particular line of text to the top.)
See also position-of-character-index.
Generic Function, cg package
Arguments: window buttons character
This generic function is called when the user types a graphical character, unless a virtual-key-down method overrides the default behavior. An application may add methods to this generic function to respond to keyboard events in its windows.
window is the window that had the keyboard focus when the event occurred. The keyboard focus is usually indicated by some sort of highlighting.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
character is the character that was typed. It is always a Common Lisp character object.
While a keypress will always cause virtual-key-down and virtual-key-up to be called, it will cause character-message to be called only under certain conditions. First, the keypress must indicate a graphical character. second, one of the following must be true:
The window in which the key was pressed is a dialog-mixin instance or a child or other descendant of a dialog-mixin instance.
The default virtual-key-down method must run (since this method tells the operating system to generate a character message from the virtual-key-down message).
Therefore, if an application adds a virtual-key-down method for a window that is not on a dialog, and this method does not call (call-next-method) for a particular keypress, then the default virtual-key-down method is not called, and therefore character-message will not be called for that keypress.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-item-id-equality-test property of a chart-widget. The value may be set at creation time by passing the :chart-item-id-equality-test initarg, or any time later by calling (setf chart-item-id-equality-test).
The value of this property is a function (or a the name of a function) that should return true if two chart item ID's are equivalent. The function is used whenever a chart value is being looked up from its item ID, to test whether each ID is the one that is sought.
The default value is equal, which should suffice for ordinary types of chart item ID's such as symbols, numbers, and strings. If all of the ID's are symbols, for example, then it may improve efficiency a bit to specify eq as the value of this property.
Chart item IDs are established by calls to set-chart-value or by a chart-value-returner function.
See also chart-object-id-equality-test.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-items property of a chart-widget. The value may be set at creation time by passing the :chart-items initarg, or any time later by calling (setf chart-items).
This property contains a tree of values that are displayed in a chart-widget. This tree is normally built indirectly by successive calls to set-chart-value. Values are looked up here when the chart is being drawn, or when an application calls chart-value.
An application normally does not need to access this property directly, though it could build the tree of values itself and call (setf chart-items) to set all of the values at once. Here is an example of a chart-items value:
((:values #((:value 164) (:value 152 :low-value 148) (:value 103))
:id (2005 dec 12))
(:values #((:value 168) nil (:value 145 :icon-size 6))
:id (2006 feb 3))
...)The value is a list where each element of the list represents one chart item. An element for one chart item is a property list that can contain an :id entry for the chart item's ID and/or a :values item that contains a sequence of values. The value sequence may be either a list or a vector. Each element of the value sequence is a property list that holds the values for one chart object at this chart item. This property list can contain entries for any of the allowed types of values (see set-chart-value).
In the example above, the first chart item species a value of 164 for the first chart object, a value of 152 and a low-value of 148 for the second chart object, and so on. The second chart item specifies nil as a placeholder for the second chart object (which has no value at this chart item) so that it can specify a value for the third chart object.
To avoid building this tree of values at all, use a chart-value-returner function instead.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-items-length property of a chart-widget. The value is the number of chart items that a chart-widget currently has, as a result of calling set-chart-value to add each item. Reading this cached value is more efficient than calling length on the chart-items property. An application should never set the value of this property.
See also chart-items-pushed-off.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-items-limit property of a chart-widget. The value may be set at creation time by passing the :chart-items-limit initarg, or any time later by calling (setf chart-items-limit).
chart-items-limit is the maximum number of chart items that a chart-widget will collect. The value should be a positive integer, or else nil for no limit. The default value is nil.
If set-chart-value is called with an item index that would cause the number of chart items to exceed this limit, then older chart items are first removed to avoid exceeding the limit when the new item is added. ("Older" chart items means items with the lowest indices.)
This property would typically be used when collecting data incrementally over time, to cause a chart-widget to display the most recent N pieces of data while throwing away older data for efficiency.
To temporarily exclude older items from view rather than permanently removing them, use chart-items-min-index.
See also chart-items-pushed-off.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-items-max-index property of a chart-widget. The value may be set at creation time by passing the :chart-items-max-index initarg, or any time later by calling (setf chart-items-max-index).
chart-items-max-index is the index of the last chart item of a chart-widget that should be displayed at the current time. The value should be a non-negative integer, or else nil for no maximum. The default value is nil.
If set-chart-value has been used to add items to the chart, then any item whose index is greater than this property value (if it is a number) will not appear in the chart. When the property value is nil, then no items are excluded. This property can be used to display only a subset of collected values that are of interest at the moment.
If instead a chart-value-returner function is used for looking up chart data, then this property should always be set to a non-negative integer to tell the chart the maximum item index that it should pass to the chart-value-returner function. Otherwise the chart-widget has no way of knowing how many items your function is prepared to return. (The property will arbitrarily default to 100 in this case, though that would usually not match the available data.)
This property is the maximum index that will be included, rather than the number of indeces to include. So for a chart-value-returner function to cover all values from a 100-element vector, for example, the value of this property should be 99 rather than 100.
See also chart-items-min-index.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-items-min-index property of a chart-widget. The value may be set at creation time by passing the :chart-items-min-index initarg, or any time later by calling (setf chart-items-min-index).
chart-items-min-index is the index of the first chart item of a chart-widget that should be displayed at the current time. The value should be a non-negative integer, or else nil to effectively default to zero. The default value is nil.
If set-chart-value has been used to add items to the chart, then any item whose index is less than this property value (if it is a number) will not appear in the chart. When the property value is nil or zero, then no items are excluded. This property can be used to display only a subset of collected values that are of interest at the moment.
If instead a chart-value-returner function is used for looking up chart data, then this property could be used if your function handles a range of item indeces that does not begin at zero.
To permanently remove older items rather than temporarily excluding them from view, use chart-items-limit.
See also chart-items-max-index.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-items-pushed-off property of a chart-widget.
chart-items-pushed-off is the number of chart items that have been discarded from a chart-widget by the chart-items-limit property. This will be zero if the chart-items-limit property has not been used to discard any items.
The total number of items that have been collected so far could be found by adding this value to the chart-items-length property. An application should never set the value of this property.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the chart-legend property of a chart-or-plot. The value may be set at creation time by passing the :chart-legend initarg, or any time later by calling (setf chart-legend).
A chart-legend is the table at the bottom of a chart-or-plot that shows a label for each chart object and indicates which line or set of bars in the chart display that object's values. The value is an instance of the chart-legend class.
The value of this property is always a chart-legend. If you do not pass a chart-legend instance as the value of the :chart-legend initarg when creating a chart-or-plot, then a default instance is created automatically.
See chart-or-plot, plot-widget, chart-widget and also .
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the chart-object-id-equality-test property of a chart-or-plot. The value may be set at creation time by passing the :chart-object-id-equality-test initarg, or any time later by calling (setf chart-object-id-equality-test).
The value of this property is a function (or the name of a function) that should return true if two chart object ID's are equivalent. The function is used whenever a chart value is being looked up from its object ID, to test whether each ID is the one that is sought.
The default value is equal, which should suffice for all ordinary types of chart object ID's such as symbols, numbers, and strings. If all of the ID's are symbols, for example, then it may improve efficiency a bit to specify eq as the value of this property.
Chart object IDs are established by the chart-objects property.
See also chart-item-id-equality-test.
See chart-widget, plot-widget, and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the chart-objects property of a chart-or-plot. (Despite the word "chart" in the symbol name, this property applies similarly to a chart-widget or a plot-widget.) The value may be set at creation time by passing a chart-objects initarg to make-instance, or any time later by calling (setf chart-objects).
The chart-objects property can be used to specify several attributes of the objects that are displayed in a chart-or-plot. A "chart object" is represented by one of the lines of a multi-line line graph in a chart-widget, for example, or by one of the segments in each bar of a stacked bar graph (also in a chart-widget), or by a group of points that are drawn with a particular icon in a plot-widget. If a chart or plot displays only a single object, then there may be no reason to specify this chart-objects property.
The description of each object can include attributes such as its object-id (an arbitrary identifier), a label to display in the legend, whether to associate the object with a primary or secondary value-axis, and/or whether to currently exclude the object from the chart or plot.
The chart-objects value is a sequence (a vector or list) where each element represents one chart object. The first element of the sequence is said to have an object-index of 0, the second element an object-index of 1, and so on. The element for each object is a property list of keywords and values. Here are the keys that may be used in the plist for an object:
:id - The ID of an object may be any sort of value, though the chart-object-id-equality-test function should be suitable for the values used. Typically it is a symbol. If nil or unspecified, an object's ID will default to the zero-based index of the object in the chart-objects sequence. This ID value will be passed to the chart-value-returner function of a chart-widget, or to the plot-value-returner function of a plot-widget, if one is used. An application can pass the ID to chart-value, set-chart-value, plot-value, or set-plot-value. Also, if no :label value is supplied here for an object, then the ID value is used to derive a label string to display for the object in the legend (typically modified by an on-print-chart-object function).
:label - This value can be a string to display for the object in the chart-legend of a chart or plot. If nil or unspecified, a label will be derived from the object's ID. Supplying this value for every object removes the need to write an on-print-chart-object function. If both are supplied, then an explicit label string will override the function.
:exclude - If a true value is specified for this key, then the object will currently not be drawn in the chart or plot. Also, if the range-bottom or range-top is automatically computed for a value-axis, then the object's data will not affect the determination of the range. This :exclude value will be toggled on or off automatically if the click-to-toggle-inclusion property of the chart-legend is true and the user clicks on the object's label in the legend.
:value-axis (chart-widget only) - This value should be either 1 or 2, though 1 is the default when nil or unspecified. A value of 1 means that a chart object will be associated with the primary value-axis of the chart-widget, which is drawn either on the left side or the bottom side of the chart (depending on the value of the chart-orientation property). A value of 2 will associate the object with the secondary value-axis, which is drawn either on the right side or the top side of the chart. A secondary value-axis is drawn only when one or more chart objects explicitly specify a value of 2 here in the chart-objects property. When two value axes are used, they can have different ranges, which is useful to compare two sets of values that are measured on different scales.
:x-axis (plot-widget only) - This works like :value-axis for a chart-widget, except that it applies to the value axes that always lie horizontally along the bottom or top of a plot-widget. 1 indicates the lower axis while 2 indicates the upper axis.
:y-axis (plot-widget only) - This works like :value-axis for a chart-widget, except that it applies to the value axes that always lie vertically along the left or right side of a plot-widget. 1 indicates the left axis while 2 indicates the right axis.
If the chart-objects property is replaced with a different vector or list, then the chart-or-plot will be updated automatically to reflect the new value. But if you modify the existing vector or list, then the widget will not know that anything has changed, and so you would need to call update-chart-widget explicitly to update the display.
Here is a sample chart-objects value that might display bowling scores in a chart-widget for Doris and Hubert, overlaid with the room temperature for each bowling event. Explicit legend labels are supplied so that no on-print-chart-object function needs to be written. The bowling scores will default to being displayed along the scale of the primary value axis, while the temperatures will use the scale of a secondary value axis. Hubert will (for now) be excluded from the chart.
#((:id :doris :label "Doris")
(:id :hubert :label "Hubert" :exclude t)
(:id :temperature :label "Temperature" :value-axis 2))See chart-widget, plot-widget, and also .
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-orientation property of a chart-widget. The value may be set at creation time by passing the :chart-orientation initarg, or any time later by calling (setf chart-orientation).
chart-orientation is a value that specifies whether the value axis of a chart-widget is oriented vertically or horizontally. The value should be one of the keywords :vertical or :horizontal. The default value is :vertical, for the typical case where a chart's value-axis is vertical and its data items are laid out along a horizontal item-axis.
The values of each axis may also be ordered in either direction; see invert-axis.
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments: chart-widget &key item-index object-index item-id object-id (value-type :value)
Returns an individual value that is in a chart-widget. This could be a value that was added by calling set-chart-value or a value that's returned by the widget's chart-value-returner function if it has one. The value will be nil if the chart does not contain a value for the specified item, object, and value-type, and otherwise it will be a number.
chart-widget is the widget to be accessed.
The keyword arguments are:
item-index is the zero-based index of the chart item to access, or nil to not specify an item index. Either this argument or item-id must be true. item-index takes precedence if both are true. The widget's chart-item-id-equality-test is used to find a matching item-index.
object-index is the zero-based index of the chart object to access, or nil to not specify an object index. The default is zero if neither this argument nor object-id is true. object-index takes precedence if both are true. The widget's chart-object-id-equality-test is used to find a matching object-index.
item-id is the arbitrary ID of the chart item to access, or nil to not specify an ID.
object-id is the arbitrary ID of the chart object to access, or nil to not specify an ID.
value-type is the type of to return. This argument may be one of the following keywords:
:value: the "main" value of a chart item and object pair.
:from-value: an optional starting value for a bar in a bar graph.
:high-value: an optional value that's normally greater than the main value.
:low-value: an optional value that's normally less than the main value.
:icon-size`: an optional size for a built-in icon drawn on a line graph.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-widget
The value of this property can be a function (or the name of a function) that supplies the data values to be displayed in a chart-widget. Otherwise it should be nil (the default), in which case the chart's data must be supplied by calling set-chart-value multiple times. chart-widget must be a chart-widget.
The function will be called automatically every time the chart-widget draws a value. The arguments to the function indicate which chart item and object it is drawing, and which type of value. The function should return a number to display (or an item ID; see below), or else nil if that type of value should not be drawn at all.
Generally when using a chart-value-returner you should also specify the chart-items-max-index property of the chart-widget, and maybe also the chart-items-min-index property, to tell the chart the range of item indices that it should pass to the function. And if the chart contains more than one object, then you should also set up the chart-objects property to tell the chart the range of object indices that it should pass to the function (and typically their object IDs as well).
Note that in the inspector this property is on the Events tab because its value is a function, though it is not actually handling window system events.
See the page for the chart-widget class for an example of a chart-value-returner function, or the chart-widget tutorial (in cg-chart-widget.html for further examples.
The parameter list of a chart-value-returner function should be this:
Arguments: chart-widget value-type item-index object-index object-id
These arguments are:
chart-widget is the chart being drawn.
value-type is the type of value that is being drawn. This will be one of the following keywords:
:id: the arbitrary ID to use for a chart item.
:value: the "main" value of a chart item and object pair.
:from-value: an optional starting value for a bar in a bar graph.
:high-value: an optional value that's normally greater than the main value.
:low-value: an optional value that's normally less than the main value.
:icon-size: an optional size for a built-in icon drawn on a line graph.
If value-type is :id, then the function should return an arbitrary value to use as the ID of the chart item, or else nil to default the ID to the item's zero-based index. This ID may then get passed to the item-axis' on-print-major-label or on-print-minor-label function to produce the string that is displayed on the item-axis tic mark for this chart item.
If value-type is anything other than :id, then either a number should be returned to display the specified type of value, or nil should be returned to not display that type of value.
(If a particular type of value will never be drawn, then for efficiency that value type could be removed from the value-types property of the chart-widget. That will prevent the chart-value-returner function from ever being called for that type of value.)
item-index is the zero-based index of the chart item being drawn. One exception is that when value-type is :id, the object-index and object-id arguments may be nil.
object-index is the zero-based index of the chart object being drawn.
object-id is the arbitrary ID of the chart object being drawn. This will be meaningful only if you have set up the chart-objects property of the chart-widget to specify object IDs; otherwise an object-id will default to the object-index.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-widget
Returns the value of the chart-view property of a chart-widget. The value may be set at creation time by passing the :chart-view initarg, or any time later by calling (setf chart-view).
This property indicates the type of chart to draw. The value may be :bar to draw a bar chart, or :line to draw a line graph. The default value is :line.
The same data are used for either view, though values of types :high-value and :low-value are used only by the bar chart view, and values of type :icon-size are used only by the line graph view. (See set-chart-value and chart-value-returner for information on the various types of data values.)
When the value is :bar, then the bar-chart-view instance in the bar-chart-view property is used to draw a bar chart. When the value is :line, then the line-graph-view instance in the line-graph-view property is used to draw a line graph instead.
See chart-widget and also cg-chart-widget.html.
Function, cg package
This function is no longer supported. The behavior of the following code is similar to the old behavior of this function:
(defun my-check-fixnum (&rest args)
(dolist (i args)
(if (null (excl:fixnump i))
(error "Non fixnum ~S passed to my-check-fixnum" i))))Generic Function, cg package
Arguments: menu-item
This menu-item property is no longer used. It was related to the GTK version of CG, which is no longer supported.
Generic Function, cg package
Arguments: list-view-item
This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.
Returns the value of the checked property of a list-view-item of a list-view control. The value may be set at creation time by passing the :checked initarg to make-instance, or any time later by calling (setf checked).
This property specifies whether a list-view-item on a list-view control is currently checked. This can be true only if the show-check-boxes property of the list-view is true to show the special column of check boxes. The default value is nil.
Typically an application would call checked on various list-view-items of a list-view control once the user has exited the dialog that contains the list-view, to see which items the user has checked. An application can also call (setf checked) on a list-view-item to set whether that item is checked or unchecked.
The generic function (setf checked) will also be called whenever the end user interactively toggles the checked state of an item by clicking on it. An application could add an :after method to catch whenever the checked state changes, though it is more typical to give the list-view control an on-check function, which will be called when the state of any of its check boxes has changed.
Generic Function, cg package
Arguments: menu-item
This menu-item property is implemented only on the Windows platform.
Returns the pixmap, if there is one, that was specified to be displayed on the left side of the menu-item when the menu-item is checked (meaning when it's selected property is true). If no such pixmap was specified, then nil is returned.
The pixmap can be specified by passing a checked-pixmap initarg when calling make-instance to create the menu-item. The value should be either a pixmap or nil, and the default is nil. The value would be used only if the menu-item's checkable property is true.
If a menu-item's checkable and selected properties are both true but the checked-pixmap property is nil, then a default check mark pixmap is displayed.
See also unchecked-pixmap.
Generic Function, cg package
Arguments: basic-pane
Returns true if basic-pane is not a top-level window; that is, if it has a non-owner parent window, not counting the screen.
Function, cg package
Arguments:
This function displays a dialog containing the list of installed Windows printers. If you select a printer from this dialog and click OK, then Allegro CL modifies the win.ini file to make the chosen printer the current default printer for all Windows applications (just as if you selected it using the Windows Control Panel). Allegro CL will now use that printer as well.
Generic Function, cg package
Arguments: class-or-name
This symbol is exported only because it can be included in code that is generated for an object-editor form or a class-grid on a form. It should not be used by applications.
Generic Function, cg package
Arguments: grid-row grid-column &key (row-number 0) (column-number 0)
Removes the cached value (if any) for the grid cell that is defined by the intersection of grid-row (which must be a grid-row) and row-number with grid-column (which must be a grid-column) and column-number. Also calls invalidate-cell to cause the cell to be redrawn, reading a possibly updated application value to display. See cache-cell-values.
Generic Function, cg package
Arguments: grid-widget
Removes the cached values for all cells of grid-widget (which must be a grid-widget). Also calls invalidate on grid-widget to cause it to be redrawn with possibly updated application values. See cache-cell-values.
Generic Function, cg package
Arguments: row column &key (row-number 0) (column-number 0)
Clears the delayed interactive edit that is being held for a particular cell of a grid-widget (if any), and then calls invalidate-cell to redraw the cell with its previous values. An application might call this function if the user indicates that they made a mistake while editing a particular cell, if the grid is using the delay-write-cell-value option. Call clear-delayed-cell-values instead to clear the delayed values of all of the grid's cells at once.
Generic Function, cg package
Arguments: grid-widget
Clears all delayed interactive edits that are being held by grid-widget (which must be a grid-widget), and then calls invalidate on grid-widget to redraw it with the previous values. An application typically would call this function just after it asks the user to confirm or reject current edits to the grid, and the user rejects them. See delay-write-cell-value and clear-delayed-cell-value.
Generic Function, cg package
Arguments: window
This generic function is called whenever a window loses the keyboard focus. Applications may add :after methods in order to be notified when this occurs. An application should not call clear-focus itself, and the built-in methods should not be overridden. See also set-focus.
Generic Function, cg package
Arguments: grid-widget row-section column-section drawing-pane section-box
clear-grid-section is called internally whenever all or part of a grid-section (of a grid-widget) is redisplayed. For efficiency, it is called a single time to draw the empty background of an entire section before draw-cell is called for each of the individual visible cells of the section. The default method simply calls erase-contents-box to clear the section.
An application should not call this function, but may add methods to override the default method if desired. One case where this may be useful is to reduce flashing that may occur for example if clicking and dragging in a cell produces an animation effect by repeatedly changing the domain value represented by the cell and invalidating the cell to redraw it at each stage. If the draw-cell methods for all of the cells in the grid-section are written to draw the entire contents of the cells, then clear-grid-section need not do anything and so a method that does nothing could be added to eliminate the flashing caused by the default method clearing the background.
The arguments are:
grid-widget: the grid-widget of which the grid-section is a part.
row-section and column-section: these define the intersection where the clearing is done.
drawing-pane: this is the child window on which drawing occurs. When clear-grid-section is called, the background-color of the drawing-stream is set to the background-color of the grid-widget.
section-box: this is the box in the drawing-pane's stream coordinates that covers the section that should be cleared.
See also draw-cell, draw-grid-section, draw-grid and grid-widget.
Generic Function, cg package
Arguments: graphical-stream
Causes the current named gradient, if any, to no longer be in effect. This simply sets the variables that were set by set-named-gradient back to nil, and the stream argument is ignored.
Typically you would use the macro with-named-gradient instead of this function.
graphical-stream is the Common Graphic stream on which filling was done using the gradient.
This generic function is implemented only on Windows and JavaScript/HTML.
See also named-gradient.
Function, cg package
Arguments: &optional stream
Resets the contents of the argument stream to the background texture that initially filled the stream. The function is useful for clearing windows. Changes to the background-color or background-texture often do not take effect until clear-page is called. stream should be a cg-stream.
If stream is a text-edit-pane, clear-page removes all text in the pane.
Function, cg package
Arguments: editable-text
Sets the string of a editable-text control editable-text back to the empty version of its template. See template-string.
Generic Function, cg package
Arguments: dialog widget
click-event is called automatically whenever the user left-clicks on a control that implements the click event. The default method calls the on-click event-handler function of the control if it has one.
Click behavior could be specified for a whole control subclass by defining a click-event method for that subclass rather than giving the same on-click event-handler function to every instance of the subclass.
Generic Function, cg package
Arguments: grid-column
This is a property of the classes check-box-column-mixin and combo-box-column-mixin, which implement pseudo-controls in grid-widget columns. When set to true, the user must click on the small gadget within the cell in order to activate it by clicking. When nil, the user can click anywhere in the interior of the cell. (Pressing the spacebar or return key will still activate the gadget regardless of the value of this property.)
The default is true. The advantage of having this property on is that the user can click in the cell to simply give it the keyboard focus, without changing the value or showing a list of choices. The disadvantage is that the clickable area is smaller.
Generic Function, cg package
Arguments: standard-object
Returns the value of the click-off property for its argument. This property determines whether a button can be un-pressed by clicking it when it looks pressed in.
This property applies to button controls that remain depressed after clicking them. Sometimes it is desirable to allow your users to un-press the button by clicking a second time, while other times it is desirable to require some other action such as clicking another button in the same cluster or within the same multi-picture-button.
Here are the possible values and their effects:
nil`: users can only deselect the button by clicking on another button in the same cluster (or by setting the value programmatically).
t: users can deselect the button by clicking on it again once it has been selected, i.e., the control will toggle on and off.
click-off is a property of the multi-picture-button, picture-button, and radio-button classes.
Generic Function, cg package
Arguments: cursor
Returns (or sets with setf) a position object that determines what point within the mouse cursor image will register as the clicked position when the mouse is clicked. With an arrow cursor, for example, the click-position would be expected to be at the pixel that defines the very tip of the arrow. A position with coordinates (0,0) indicates the upper left corner of the image.
The argument must be a mouse cursor instance.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the click-to-toggle-inclusion property of a chart-legend. The value may be set at creation time by passing a click-to-toggle-inclusion initarg to make-instance, or any time later by calling (setf click-to-toggle-inclusion).
If true, then the end user can interactively toggle whether particular chart objects are currently included in the chart-widget or plot-widget by clicking on the labels for the objects in the legend. An object's label will be grayed in the legend when it is excluded. The default value is nil because users typically will not expect this behavior.
An application could implement side effects when an object is toggled on or off by supplying an exclude-or-include-chart-object method.
See the description of the :exclude key on the page for chart-objects.
Generic Function, cg package
This function has been removed in the 7.0 release. In earlier releases, it returned the Lisp clipboard object. That object is now the value of the variable *clipboard*.
Generic Function, cg package
Arguments: clipboard-format
This generic function is called whenever the contents of the Lisp clipboard stack changes. An application could add a method to this generic function to catch whenever this happens.
The Lisp clipboard and the Windows clipboard usually change at the same time when functions such as push-lisp-clipboard, pop-lisp-clipboard, copy-command, and cut-command are called, but if the function (setf clipboard-object) is called directly to change the Windows clipboard, then the Lisp clipboard is not changed and clipboard-changed is not called.
The argument is the current value of *clipboard*, reflecting the new state. This value is a list of conses, where the car of each cons is an object on the clipboard and the cdr is one of the symbols :text, :rich-text, or :pixmap indicating the Windows clipboard format of that object. The default method does nothing, so an application could simply replace it with a primary method specializing on t, or add an :after method specializing on t.
See cg-clipboard.html.
Generic Function, cg package
Arguments: *object *
Returns a keyword symbol that indicates which clipboard format of the underlying platform's system-wide clipboard is suitable for the specified data object. The returned value may be useful for passing to push-lisp-clipboard or (setf clipboard-object).
The default methods return :pixmap for a pixmap and :text for anything else. The other possible format, :rich-text, is never returned because that would require parsing a string to see if it is a valid rich text string, and guessing that it is intended to be pasted as one.
See cg-clipboard.html.
Generic Function, cg package
Arguments: configuration
Returns or sets with setf the maximum number of cut or copied objects that the clipboard will hold. (Once this number of items are on the clipboard, adding another will remove the oldest item.) clipboard-history-limit is a property of the configuration class.
See cg-clipboard.html.
Generic Function, cg package
Arguments: clipboard-format
This generic function returns (or sets with setf) the value of the system clipboard for a specified format. The argument may be either :text, :rich-text, or :pixmap to indicate the format. On Windows, other custom locations can also be specified as clipbord-format values. See the Windows Note below.
CG/JS Note: The :rich-text format is not supported. And the :pixmap format works only within a CG application, and not system-wide.
When using the setf, the value should match the specified format, where :text indicates a regular Lisp string, :rich-text indicates a regular Lisp string that happens to be in rich text format (such as can be retrieved by calling rich-edit-range on a rich-edit widget or rich-edit-pane), and :pixmap indicates a Common Graphics pixmap object. (Common Graphics uses the "device-independent bitmap" Windows clipboard format to pass pixmaps on the Windows clipboard to and from other applications.)
The setf of this function has an additional keyword parameter called empty-clipboard, which defaults to t. When true, this causes the clipboard to be completely cleared before placing the new value onto the clipboard. This ensures that no values of other data formats are left on the clipboard along with the new value. If it is desired to place data of multiple formats onto the clipboard, then specify this argument as nil when adding successive formats, as in:
(setf (clipboard-object :text :empty-clipboard nil) "foo")Note that the setf of this function does not modify the Lisp clipboard stack. To modify both the system clipboard and the Lisp clipboard stack, use a function such as push-lisp-clipboard or copy-command rather than (setf clipboard-object).
See cg-clipboard.html.
The older functions clipboard-string and clipboard-pixmap are deprecated in favor of this newer single function.
Windows File Explorer note: On Windows, the argument may also be the keyword :file-list. If the most recent copy that was done (system-wide) was copying a set of files in the Windows File Explorer, then this will return a list of the full path namestrings of those files. Otherwise this will return nil. Calling paste-command will retrieve and use this special value if it is there (which should be OK because the Windows clipboard apparently never holds both a :text value and a :file-list value at the same time).
It is possible to place text at alternate "locations" on the Windows system clipboard, by simply passing the clipboard-format argument as any symbol other than the standard :text, :rich-text, or :pixmap. This is probably useful only if you have multiple standalone Lisp applications, or multiple running instances of a single application, where they are all aware of the same location names. Then one instance could place text at various locations, and another instance could read the text at whichever locations it is interested in.
Here's an example, where typically one Lisp application instance would do the first pair of calls, and a second instance might do the second pair of calls, but it works in a single Lisp as well.
(setf (clipboard-object :text) "primary text")
RETURNS "primary text"
(setf (clipboard-object :place-two :empty-clipboard nil) "secondary")
RETURNS "secondary"
(clipboard-object :text)
RETURNS "primary text"
(clipboard-object :place-two)
RETURNS "secondary"Function, cg package
Arguments:
This function is deprecated. Use clipboard-object instead.
clipboard-pixmap creates a Common Graphics pixmap object from the device-independent bitmap (DIB) that is currently on the Windows clipboard, and returns it. (If there is no DIB currently on the clipboard, then nil is returned instead.) This allows a Common Graphics application to retrieve and use a pixmap that was placed ("copied") onto the clipboard by another application.
The setf function, (setf clipboard-pixmap) places a Common Graphics pixmap onto the Windows clipboard as the current device-independent bitmap (DIB), ready for other applications to "paste" it or otherwise retrieve it.
pixmap is the pixmap to "copy" to the Windows clipboard.
Example:
(setf (clipboard-pixmap) my-pixmap)See cg-clipboard.html.
Function, cg package
Arguments: clipboard-format
This function is deprecated. Use clipboard-object instead.
The function returns a Lisp string for the current Windows clipboard object. clipboard-format may be either :text or :rich-text.
The setf function sets the current Windows clipboard value for clipboard-format to a specified value.
clipboard-format currently must be either :text or :rich-text. value currently must be a either a plain-text or rich-text string, according to value of clipboard-format.
See cg-rich-text.html for information on rich text editing in Common Graphics. See also cg-clipboard.html.
Function, cg package
Arguments: stream
This function and the related nclipping-box returns two values. The first is a box representing the current clipping box of stream relative to the current origin. stream should be a cg-stream but may not be a text-edit-window or a text-edit-pane.
The second returned value, which is one of the symbols :simple, :complex, or nil, indicates which type of clipping region the window currently has. :simple means that box returned as the first value exactly describes the clipping region. :complex means that the box encompasses a non-rectangular clipping region; Common Graphics does not provide any further information about this region however. nil means that the clipping region is empty (of size zero) and so nothing can be drawn on the stream currently; in this case the first return value is the box (0 0 0 0), though the arbitrary "position" of this box at (0 0) is not meaningful.
Note that the box returned (as the first value) is not merely the value that may have been set by a call to (setf clipping-box) or with-clipping-box; it also reflects how the window is partly or fully covered by other windows and how it is scrolled. Specifically, the returned box is the smallest box containing the currently visible parts of the window's interior (in stream units), intersected with the box most recently specified by a call to (setf clipping-box) or with-clipping-box, if any. A window whose interior is completely covered will always return the box (0 0 0 0) and a second value of nil to indicate a currently empty clipping region.
An application may call (setf clipping-box) at any time to set the current clipping-box of a Common Graphics stream. The value argument may be either a box to establish clipping, or else nil to remove all clipping. The macro with-clipping-box is a handy alternative because it guarrantees that the original clipping-box will be restored after its body executes.
While the function (setf clipping-box) and the macro with-clipping-box are often useful for establishing a clipping region, applications generally are not expected to have a need to call clipping-box or nclipping-box to retrieve the current region. The functions are not reliable for recalling the region that was explicitly set, since the returned box is also affected by how the window is covered. Furthermore, all drawing code for a window (other than a bitmap-pane) normally should be placed within a redisplay-window method, which always receives a box argument denoting the area that needs to be redisplayed, and the clipping-box of the window is set to this box automatically during the call to redisplay-window.
Platform note: the box that is returned will exclude any part of the window that happens to be covered by other windows on the Microsoft Windows platform.
Generic Function, cg package
Arguments: basic-pane
Returns true if basic-pane has an active close button (a control on the title bar which closes the window when clicked) and nil otherwise. When nil, a close button appears but it is unavailable (grayed out).
The close-button property may not be changed on an existing window, and must instead be specified with the inspector when designing a window (using a form) or with the :close-button initarg of make-window. (It can be changed using the inspector when designing a form but not for a running window or control, either in the IDE or in an application.)
Function, cg package
The symbol naming this operator has been moved to the dde package. Please see close-dde.
Generic Function, cg package
Arguments: image-list
Closes an image-list so that it is no longer usable unless it is re-opened by calling open-image-list. It is not expected that applications will normally need to call this function, but it may be useful to call this for image-lists which are not currently needed in order to save space or Windows resources if a large number of image-lists are used over time.
Common Graphics will automatically re-open a closed image-list whenever it is assigned to a list-view control, such as by calling (setf small-image-list). But care should be taken never to close an image-list which is currently in use by a list-view control. See the description of the list-view control.
See list-view.
Function, cg package
Arguments: menu
Closes the specified menu and all of its descendent cascading submenus, by recursively calling the standard Common Lisp function close on each one. CG does not do this automatically because it allows adding a menu as a child of multiple parent menus.
Closing menus is likely only needed in rare cases to avoid depleting limited resources of the underlying Windowing system, in particular the Microsoft Windows limit of 32,767 total menu-items in an application.
See also close-window-and-menus.
Generic Function, cg package
Arguments: outline item-value &optional no-redisplay-p
Causes the subitems of the outline-item of outline whose value is item-value to be hidden.
Alternately, (setf state) may be called to change the state of an outline-item. This may by more efficient if you have the outline-item object in hand, rather than its value only. See the description under the heading State on outline-items near the bottom of the page for state.
Generic Function, cg package
Arguments: stream palette
Destroys palette, releasing any operating system storage. palette must not be the palette of any open stream.
stream is for discrimination purposes only; (screen *system*) (see screen and *system*) may normally be used. If a stream, stream should be a cg-stream.
Generic Function, cg package
Arguments: pixmap
Tells the operating system to destroy its device-dependent pixmap resource that it is using for a pixmap object, and sets the pixmap-handle of the pixmap object to nil. After this is done, the pixmap can still be used, but will be drawn by sending the array of pixels to the operating system each time rather than passing only the handle of the operating system's internal version of the pixmap.
open-pixmap-handle can be called again later to create a new device-dependent pixmap if desired. This function does nothing if the pixmap object already has no handle. Calling this function may be useful to save operating system pixmap resources (though a handle is not created and given to the pixmap object to begin with unless open-pixmap-handle is called to do this).
Function, cg package
The symbol naming this operator has been moved to the dde package. Please see close-port.
Function, cg package
The symbol naming this operator has been moved to the dde package. Please see close-server.
Generic Function, cg package
Arguments: outline
Returns (or sets with setf) the value of this property of outline. This property determines whether all descendent outline-items of an outline-item that is being closed are also closed.
When true, closing and then re-opening an outline-item results in the item's subitems reappearing without any of their subitems reappearing, even if they were visible before closing the outline-item. When false, closing and reopening an outline-item results in the tree of subitems reappearing just as it was before the outline-item was closed. (The Windows File Explorer works as if this property were false. Suppose some folders in the C drive have subfolders that are displayed. Clicking on the boxed - next to the C drive icon renders all folders in C invisible but when you then click on the boxed + next to the C drive icon, the folders reappear and those folders that were open before are open again.)
The value of this property defaults to t for backward compatibility, but may be set to nil to achieve behavior similar to the Windows File Explorer.
close-subtrees-on-close is a property of the outline class.
Function, cg package
Arguments: window
Closes the specified window, and also calls close-menu-and-submenus on the menu-bar of the window, if it has one.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns the pixmap instance used to indicate a non-expanded outline item. closed-pixmap is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns (or sets with setf) the symbol name of the pixmap instance to display on non-expanded outline-items. When setting this value, the pixmap that is set should have been placed into the set of cached pixmaps at some point by calling cache-pixmap on it.
closed-pixmap-name is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns (or sets with setf) the path namestring of the .bmp pixmap file from which the pixmap instance to display on non-expanded outline-items was originally read (if any). When this value is set, load-pixmap is called on the path namestring, a pixmap object is created from the information that is read, and the pixmap is cached by calling cache-pixmap on it so that it may later be retrieved by calling find-pixmap on its name.
closed-pixmap-source is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: windows-button
Returns the value of the cluster property of windows-button. This property groups picture-button or radio-button controls into clusters (and also menu-items, see below). If a user clicks one button in the cluster, that button will be turned on and all other buttons in the cluster turned off.
Clusters are logical associations independent of physical placement on the dialog, but controls must be on the same dialog to be in the same cluster. All of the buttons in a single cluster will have an identical Lisp symbol (such as :cluster-1 or :send-form-button-panel) in their cluster property. The controls are also often arranged visually as a group, perhaps in a group-box.
The cluster property can also be used with menu-items. A set of contiguous menu-items can act like a set of radio-buttons, where calling (setf selected) to mark one of the menu-items as selected automatically deselects all of the other menu-items in the group. The group is set up by setting the cluster property of each menu-item in the group to the same arbitrary symbol, just as with radio-button widgets. In addition, a menu-item whose cluster property is non-nil will be marked by a small round dot when selected rather than with a check mark. It is a good idea to place a menu-separator between the menu-items in a cluster and any other menu-items on the same menu to clarify to the end user which items are in the group.
In the following example, each time (pop-up-menu my-menu) is called and a menu-item is selected, the menu's on-click function toggles whether that item is selected, which is apparent only when the menu is shown a further time. The "Independent" item is not in a cluster, while the other two items are in a cluster named :a. Selecting one of the items in the cluster will unselect the other item in the cluster if it was selected, but will not unselect the "Independent" item if it was selected.
(defparameter my-menu nil)
(setq my-menu
(open-menu (list (make-instance 'menu-item
:title "Independent")
menu-separator
(make-instance 'menu-item
:title "One"
:cluster :a)
(make-instance 'menu-item
:title "The Other"
:cluster :a))
'pop-up-menu
(screen *system*)
:on-click #'(lambda (menu menu-item stream)
(declare (ignore menu stream))
(setf (selected menu-item)
(not (selected menu-item)))
(title menu-item))))
(pop-up-menu my-menu) ;; call this multiple timescluster is a property of the picture-button, radio-button, and menu-item classes.
Generic Function, cg package
Arguments: hotspot-or-text-edit-pane
Hotspot: when the argument is a hotspot, returns (or sets with setf) the color in which to draw a hotspot.
Text-edit-pane: for a text-edit-pane, color returns two values: (1) an rgb object for the color of the first character in the selected range of text-edit-pane (or the character at the cursor), and (2) true if and only if the whole selection is the same color.
Again, for a text-edit-pane, (setf color) sets the color of the selected range of the argument text-edit-pane to new-value, which should be an rgb object (see make-rgb).
A text-edit-pane argument must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: cg-configuration
Returns the color that is used by colorize-source-code for literal characters, or nil to avoid colorizing literal characters at all.
The value may be set by calling (setf color-for-characters). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-characters (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Arguments: cg-configuration
Returns the color that is used by colorize-source-code for comments (including block comments), or nil to avoid colorizing comments at all. This is probably the most useful type of source code colorization, to visually offset comments from actual code. Options for other types of colorization could be set to nil if they result in too much overall color.
The value may be set by calling (setf color-for-comments). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-comments (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Arguments: cg-configuration
Returns the color that is used by colorize-source-code for symbols that are external in Allegro packages other than the common-lisp, cg, and ide packages, or nil to avoid colorizing these symbols at all. This color may be useful for warning when you have mistyped an Allegro symbol, or to remind you that a particular function is built into Allegro rather than being defined by your application.
The colorization is based only on the symbol's package and external status, and will occur even where the symbol is not being used as the function or variable for which it is exported.
The value may be set by calling (setf color-for-external-allegro-symbols). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-external-allegro-symbols (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Returns the color that is used by colorize-source-code for symbols that are external in the cg and ide packages, or nil to avoid colorizing these symbols at all. This color may be useful for warning when you have mistyped a Common Graphics symbol, or to remind you that a particular function is a Common Graphics function rather than one of your own.
The colorization is based only on the symbol's package and external status, and will occur even where the symbol is not being used as the function or variable for which it is exported.
The value may be set by calling (setf color-for-external-cg-symbols). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-external-cg-symbols (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Arguments: cg-configuration
Returns the color that is used by colorize-source-code for symbols that are external in the common-lisp package, or nil to avoid colorizing these symbols at all. This color may be useful for warning when you are about to inadvertently redefine a standard Common Lisp symbol, or when you have mistyped one.
The colorization is based only on the symbol's package and external status, and will occur even where the symbol is not being used as the function or variable for which it is exported.
The value may be set by calling (setf color-for-external-cl-symbols). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-external-cl-symbols (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Arguments: cg-configuration
Returns the color that is used by colorize-source-code for global variables and constants, or nil to avoid colorizing global variables and constants at all. Specifically, this applies to symbols for which boundp is true when the colorization is done.
The value may be set by calling (setf color-for-global-variables). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-global-variables (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Arguments: cg-configuration
Returns the color that is used by colorize-source-code for literal strings, or nil to avoid colorizing literal strings at all. This may be especially useful for very long strings, to make the boundaries of the strings more apparent.
The value may be set by calling (setf color-for-strings). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-strings (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Arguments: cg-configuration
Returns the color that is used by colorize-source-code for function name symbols in non-allegro packages, or nil to avoid colorizing these symbols at all. Specifically, this applies to symbols for which fboundp returns true when the colorization is done, and whose home packages are not packages that are built into Allegro. This may be useful for determining when you have mistyped the name of a function that is defined by your application.
The value may be set by calling (setf color-for-user-functions). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.
(setf (color-for-user-functions (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))Generic Function, cg package
Arguments: stream rgb
Converts rgb into a color-number. The nearest matching color in stream's palette is returned. Returns nil if stream's palette is :rgb. See cg-color-palettes.html.
Generic Function, cg package
Arguments: rich-edit-pane
Calls color-string-at-index on rich-edit-pane, passing the current text cursor position as the index argument. The current text cursor position may be found with
(cl:file-position rich-edit-pane)The returned string will be the one around the text cursor which is in the color of the character just before the text cursor. The color is returned as a second value, as with color-string-at-index.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: rich-edit-pane index
Returns two values:
(1) the string that surrounds the character at index in rich-edit-pane and which is in the color of the rich-edit-pane at that position (in other words, the color of the character just before the index position).
(2) the color of the string as an RGB color object.
If the text just before index is black, then it is assumed that the cursor is not in a special color string, and nil is returned immediately to avoid searching through a lot of non-color text. Otherwise the two values mentioned above will be returned.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: split-bar
Returns the color-under-mouse property of a split-bar widget. The value may be set at creation time by passing the :color-under-mouse initarg to make-instance, or any time later by call (setf color-under-mouse).
This is the color of the split-bar widget when it is under the mouse cursor but it is not being dragged.
The value may be either an RGB color object (see make-rgb), or a constant symbol or global variable whose value is an RGB, or nil to use the system-edge-shadow-color, or else t to match the parent window's background color, making the split-bar invisible. The value may be set at creation time by passing the :color-under-mouse initarg to make-instance, or any time later by call (setf color-under-mouse).
The default value is t to avoid distracting the user with a split-bar that flashes whenever the mouse happens to move over it. The changing mouse cursor indicates that a drag can be done there, even when the split-bar itself cannot be seen.
Generic Function, cg package
Arguments: split-bar
Returns the color-when-dragging property of a split-bar widget. The value may be set at creation time by passing the :color-when-dragging initarg to make-instance, or any time later by call (setf color-when-dragging).
This is the color of the split-bar widget while the user is dragging it to a new position.
The value may be either an RGB color object (see make-rgb), or a constant symbol or global variable whose value is an RGB, or nil to use the system-edge-shadow-color, or else t to match the parent window's background color, making the split-bar invisible. The value may be set at creation time by passing the :color-when-dragging initarg to make-instance, or any time later by call (setf color-when-dragging).
The default value is nil to draw the split-bar in a default color, to help the user see exactly where they are placing the bar.
Generic Function, cg package
Arguments: split-bar
Returns the color-when-idle property of a split-bar widget. The value may be set at creation time by passing the :color-when-idle initarg to make-instance, or any time later by call (setf color-when-idle).
This is the color of the split-bar widget when it is not being dragged and it is not under the mouse cursor.
The value may be either an RGB color object (see make-rgb), or a constant symbol or global variable whose value is an RGB, or nil to use the system-edge-shadow-color, or else t to match the parent window's background color, making the split-bar invisible. The value may be set at creation time by passing the :color-when-idle initarg to make-instance, or any time later by call (setf color-when-idle).
The default value is t to avoid distracting the user with an always-visible split-bar. The changing mouse cursor when the mouse moves over a split-bar indicates that a drag can be done there, even when the split-bar itself cannot be seen.
When changing this property from the default value of nil to something else, you will probably want to also change the color-under-mouse property, or else the split-bar would confusingly disappear when the user moves the mouse over it.
If drawing the split-bar as a simple colored line is not adequate, then an on-redisplay function could be supplied to draw the split-bar in a custom way.
Generic Function, cg package
Arguments: texture color-number-0 color-number-1 bits-per-pixel
Returns a pixel-map of pixels capable of holding palette-size colors made from texture by using color-number-0 for 0 and color-number-1 for 1.
Generic Function, cg package
Arguments: cg-configuration
Returns whether source code colorization will be done automatically whenever load-file is called on a lisp-edit-pane. In the IDE, load-file is called when a file is shown in the editor. Applications may call load-file as well.
This option appears on the Editor Color tab on the Options dialog in the IDE, and may also be set programmatically by calling (setf colorize-on-load-file). The initial value is nil because colorization adds a significant delay, especially for larger files. An alternative in the IDE is to colorize only on demand by using the Colorize Definition and Colorize Buffer commands on the Edit menu.
See also colorize-source-code.
(setf (colorize-on-load-file (configuration *system*)) t)Generic Function, cg package
Arguments: cg-configuration
Returns whether source code colorization will be done automatically as editing is done in a lisp-edit-pane in which any colorization has been done already.
Specifically, a call to colorize-source-code will be made when the user types a space, closing parenthesis, or newline, as well as the first time the text cursor is moved without colorization having otherwise been done since the most recent text change.
This incremental colorization is usually very fast because it colorizes only the text between the character position where the text was changed and the beginning of the innermost s-expression that contains that character position. There may be a significant delay, though, when that character range is large.
This option appears on the Editor Color tab on the Options dialog in the IDE, and may also be set programmatically by calling (setf colorize-on-typing). The initial value is t, though it still does not do anything unless colorization has already been done in the lisp-edit-pane by some other means.
(setf (colorize-on-typing (configuration *system*)) t)When this option is enabled, the Edit | Undo command will not work as expected just after typing has triggered an automatic recolorization. The reason is that the Undo command uses functionality that is built into the text-editing control that is supplied by the underlying window system, and this control cannot distinguish a change that was made by typing from a change that Common Graphics made as part of colorization. You could avoid this problem by using only the colorize-on-load-file option and/or the Colorize Definition and Colorize Buffer commands on the Edit.
Generic Function, cg package
Arguments: lisp-edit-pane &key entire-buffer levels skip-preroll skip-invalidation from-position
Colorizes some or all of the text in a lisp-edit-pane. This is intended for use with Common Lisp source code, and results with other sorts of text would be rather arbitrary. The purpose is to visually distinguish various elements of source code so that programmers may more easily spot what they are looking for, and also to make typos more apparent. This function is used (optionally) by the IDE editor, and an application that handles source code could call this function as well.
This function may be called explicitly, and is also called automatically if either of the configuration options colorize-on-load-file or colorize-on-typing are enabled. Other configuration options control what types of elements are colorized and which color to use for each type; these options are:
The IDE never saves colorization into the file that is written from an editor buffer.
lisp-edit-pane should be the lisp-edit-pane to colorize.
If entire-buffer and levels are both nil (as they are by default), then the top-level definition that surrounds the current text cursor position (or from-position if specified) is colorized. If entire-buffer is true, then all of the text in the lisp-edit-pane is colorized. Otherwise, if levels is true then it should be a positive integer that indicates how many s-expressions outward to colorize backward from the current text cursor position (or from-position if specified). For example, if levels is 2 (and entire-buffer and from-position are nil), then the colorization will be done from the beginning of the s-expression that surrounds the s-expression that surrounds the current text cursor position, to the current text cursor position.
skip-preroll is used internally and is not intended for use by applications.
If skip-invalidation is nil, as it is by default, then the part of the lisp-edit-pane that may have changed is invalidated at the end so that it is redrawn to reveal any new colors. If it is true then no invaildation is done. Generally, true should be specified only if you know that the window will be redrawn later by some other means; this may avoid flashing caused by multiple redisplays, since the text control may redraw itself immediately when invalidated rather than waiting until no more events are queued as most windows do.
If from-position is nil, as it is by default, then the colorization is based on the current text cursor position. Otherwise it should be a character index (a non-negative integer) indicating the position on which to base the colorization.
Generic Function, cg package
Arguments: pixmap
Returns (or sets with setf) the vector of colors that are used to draw the pixels of the pixmap. This actually just accesses the texture-info-colors of the texture-info of the pixmap object, where the texture-info is kept as a sub-object for backward compatibility.
The value of this property can be the symbol :default as well as a vector of colors. This special value means to use the colors currently returned by default-pixmap-color-vector. If the colors used in the pixmap are equivalent to those returned by initial-pixmap-color-vector (and in the same order), then it may be desirable to specify :default. The reason is that Common Graphics replaces three of the colors in the default-pixmap-color-vector with colors that match the end user's color scheme (as specified in the Windows Control Panel). Specifying :default will ensure that the pixmap uses those three special colors in the end user's scheme. Specifically, the color at index 7 will be the value returned by system-dialog-background-color, position 8 will hold the system-edge-shadow-color, and position 15 (the last position) will hold the system-background-color.
colors is a property of the pixmap class.
Generic Function, cg package
Arguments: list-view column
A generic function that is called internally when the end user clicks on the header of a list-view-column. The default method sorts the list-view by the contents of the clicked column, but an application could override or add to this sorting functionality by defining additional column-click methods. See the description of the list-view control.
Generic Function, cg package
Arguments: grid-widget
Returns a list that contains the header-cell child object of every grid-column in every column-section of grid-widget (a grid-widget). The properties of each of these objects can be modified to specifically modify the drawing style of the header cell of each column.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: grid-widget
Returns an object that specifies default drawing style properties for the header-cell of each grid-column of grid-widget (a grid-widget). Setting a property value of this object will set the same property value of the header-cell of each existing column in each column-section of grid-widget to the specified value. Thereafter, the header-cell of any columns that are added to a column-section by calling (setf subsection-count) will get initial property values from this object as well.
The values of this object's properties can be the same as the values of the same properties of grid rows and columns. They can also be the special keyword symbol :defer, which means that the header cell should use the same value for that property as the other cells in that row or column. The values are initially :defer for each property, allowing you to override only the particular properties that should differ for the header cells only.
Typically you might want the font to be bold only in all column header cells. This would be the place to specify a bold font to make that happen.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: class-grid
Returns the font that is used in the header cell at the top of each grid-column of a class-grid. The value may be set with the column-header-font initarg or by calling (setf column-header-font).
Generic Function, cg package
Arguments: class-grid
Returns the section-size (height in pixels) of the row of column header cells at the top of a class-grid. The value may be set with the column-header-height initarg or by calling (setf column-header-height).
A larger value will cause column header strings to wrap to multiple lines, sometimes allowing a smaller column width to be used.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns the number of blank pixels between the array of images in a lamp widget and the label strings above or below the columns. The value may be specified at creation time with the column-label-margin initarg, or anytime later by calling (setf column-label-margin). This value is used only when the value property of the lamp widget is an array.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns the number of blank pixels by which to shift the label strings rightward above or below the columns of images in a lamp widget. The value may be specified at creation time with the column-label-offset initarg, or anytime later by calling (setf column-label-offset). This value is used only when the value property of the lamp widget is an array.
This property may be used as a fudge factor to make the labels appear as aligned as possible with the lamp images, adjusting for the internal leading of the widget's font.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns whether the label strings that are above or below the columns of images in a lamp widget are drawn vertically of horizontally. The value may be one of the keyword symbols :vertical or :horizontal. The value may be specified at creation time with the column-label-orientation initarg, or anytime later by calling (setf column-label-orientation). This value is used only when the value property of the lamp widget is an array.
Generally :horizontal is a good choice when the strings are short enough (such as a single letter) to fit horizontally above or below each column. Otherwise :vertical would be needed, though :vertical amkes the labels a bit harder to read.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns the side on which the column-labels of a lamp widget are displayed. The value may be one of the keyword symbols :top or :bottom. The value may be specified at creation time with the :column-label-side initarg, or anytime later by calling (setf column-label-side). This value is used only when the value property of the lamp widget is an array.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns a list of strings to display above or below the columns of images in a lamp widget. The value may be specified at creation time with the column-labels initarg, or anytime later by calling (setf column-labels). This value is used only when the value property of the lamp widget is an array.
The first string is displayed on the leftmost column of images, the second string on the next column, and so on until there are no more columns or strings. The strings are displayed on the column-label-side of the lamp images, with column-label-margin blank pixels in between.
Generic Function, cg package
Arguments: calendar-widget
The number of extra blank pixels to add between adjacent columns in a calendar widget.
See also the calendar class and the function ask-user-for-date.
Function, cg package
Arguments: grid-widget section-name
Returns a column-section object given its name and the grid that it is on.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: grid-widget
The list, from left to right, of a grid-widget's grid-column-sections. Each grid-column-section is a set of columns that (optionally) can be scrolled horizontally. The section of columns is clipped at some arbitrary width, and the width of the column section can (optionally) be changed by clicking on and horizontally dragging the vertical border on the right side of the section.
column-sections is a property of the grid-widget class.
Generic Function, cg package
Arguments: item-list
This function is specific to Windows, and returns nil on other platforms.
Returns the width of each column in pixels on single-item-list and multi-item-list controls. The value nil is arbitrarily interpreted as a width of 150 pixels. There is no maximum width. This value is used only if the multi-column-p property is true.
The :column-width initarg will set the column width initially, and the setf of this function may be called (on Windows only) to change the column width any time later.
Generic Function, cg package
Arguments: list-view
Returns (or sets with setf) the list of list-view-columns of a list-view control.
columns is a property of the list-view class.
Generic Function, cg package
Arguments: object-editor
Returns a list of the standard command buttons that are included on object-editor, which must be an object-editor. The value may be set at creation time with the command-buttons initarg, or any time later by calling (setf command-buttons).
The value should be a list containing any subset of the keyword symbols in the left column below. The list of all choices is the value the constant *object-editor-command-buttons*, which is the default value of this property. Each button calls an exported generic function, which is shown to the right of the button name here. An application could add custom widgets that call these functions rather than using the built-in buttons. An application could also add wrapper methods to the generic functions to intercept all usage of the command buttons (or other calls to the functions). See the doc pages for the functions for more information on the behavior of these buttons.
Button Name |
Generic Function Called |
Notes |
:first-button |
(passing |
|
:previous-button |
(passing |
|
| :next-button |
(passing :next) |
|
| :last-button |
(passing :last) |
|
| :select-button |
|
|
| :search-button |
|
|
| :save-button |
|
|
| :revert-button |
|
|
| :new-button |
|
|
| :delete-button |
|
|
| :commit-button |
|
|
| :rollback-button |
|
The order of the buttons in this property value does not make a difference because the buttons that are included are automatically layed out in certain standard positions. When creating an object-editor interactively as a form window in a project, you could move the buttons to wherever you like after the automatic layout is done.
:save-button is a default-button, and so pressing the Enter key in an object-editor will call object-editor-save (unless the keyboard focus is on some other button widget, which makes that button be the acting default button). :revert-button is a cancel-button, and so pressing the Escape key anywhere in an object-editor will call object-editor-revert.
:commit-button and :rollback-button ordinarily should not be used on an object-editor whose edited-class is not a persistent class.
Generic Function, cg package
Arguments: app
Returns as a string the value of the command-line property of app. When app is (app *system*) (see app and *system*), the command-line used to start the current Lisp invocation is returned.
command-line is a property of the app class.
Function, cg package
Arguments:
Returns as a string the version identifier of the currently running implementation of Common Graphics. Please include this information in any problem report or question about the product.
Generic Function, cg package
Arguments: window
Returns true if the argument is an instance of the common-status-bar class and returns nil otherwise.
Function, cg package
This function is no longer supported.
Generic Function, cg package
Arguments: window
Returns the dialog-item associated with window if there is one, and otherwise returns window itself.
Similar to the function dialog-item, except that dialog-item returns nil rather than the window itself when there is no associated dialog-item.
Generic Function, cg package
Arguments: comtab-mixin
Returns (or sets with setf) the comtab of a window (comtab-mixin is a mixin class which is a superclass of window classes that have comtabs, such as text-edit-pane). A comtab is conceptually a table of commands (keystrokes and chords) associated with a window. A chord is a combination of keys pressed simultaneously, such as Control-A and Escape-W.
The function set-event-function modifies the current comtab. See the description of that function for examples involving comtabs.
Function, cg package
Arguments: &rest rich-text-strings
Concatenates an arbitrary number of rich-text strings into a single rich-text string.
Note that simple concatenation (such as with concatenate) does not work with rich-text strings because each string has a header that defines fonts and so on, and also because a later string could inherit formatting from the end of the previous string. This function merges the headers and current formatting of the multiple strings as needed. If all of the arguments are either the null string or nil, then nil is returned.
Generic Function, cg package
Arguments: system
Returns the configuration associated with the argument system. The current system is the value of *system* so the current configuration is the value of (configuration *system*). The configuration is a data structure holding values for many configurable aspects of the working environment, such as the values of global variables.
All of the configuration options may be edited in the inspector by using the Tools | Inspect System Data | Configuration Options menu command. Most of them appear on the Tools | Options dialog as well, in a friendlier format. A configuration option may also be changed programmatically by setf'ing the option, which is a property of the configuration object, for example, displaying of tooltips can be disabled with the form
(setf (show-tooltips (configuration *system*)) nil)(See show-tooltips.) All configuration options are saved in the allegro-ide-options.cl when the Tools menu | Save Options Now menu command is used, or when the IDE is exited if the Tools menu | Save Options on Exit is enabled (as it is by default). If this file is deleted or renamed, then all configuration options will revert to their defaults in the next Lisp session. See The user options file allegro-ide-options.cl in cgide.html for more information on the options file.
configuration is a property of the system class.
Generic Function, cg package
Arguments: window &key pan pan-with-single-finger-vertically pan-with-single-finger-horizontally pan-with-gutter pan-with-inertia two-finger-tap zoom rotate press-and-tap
Establishes which capabilities of the gesture interface will be enabled for the specified window. The value of each keyword argument can be either t to enable the capability, nil or unspecified to disable it, or :inherit to inherit the value from an ancestor window or else the system defaults. Since unspecified values disable the associated capabilities, all capabilities that are to be enabled need to be passed on any call to this function.
Here are the meanings of the keyword arguments, all of which appear to be enabled by default (at least on the test machine) except where otherwise noted:
pan - This must be enabled to enable any panning by dragging one or two fingers across the screen. Without the other panning options, two-fingered panning will be enabled both horizontally and vertically.
pan-with-single-finger-vertically - Enables panning vertically by dragging a single finger.
pan-with-single-finger-horizontally - Enables panning horizontally by dragging a single finger. This one appears to be disabled by default to allow the default behavior to select text instead.
pan-with-gutter - If enabled, restricts panning to either the horizontal or vertical direction, whichever one the gesture begins with, unless the user also moves in the other direction by some minimum amount that breaks out of the gutter.
pan-with-inertia - If enabled, calls to gesture-event will continue to be made for a brief period after a panning gesture ends during a drag, to allow the pan to gradually slow to a halt.
two-finger-tap - Enables a simple tap with two fingers.
zoom - Enables a two-finger pinch or spread gesture.
rotate - Enables a two-finger circular motion around a central point. This one appears to be disabled by default.
press-and-tap - Enables a gesture where one finger touches the screen momentarily, followed by a second finger while the first is still on the screen.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: grid-widget selected-subsections
This generic function is called when the user presses the delete key while a grid-widget has the keyboard focus, and whenever delete-selected-subsections is called with a true confirm argument (as it is by the delete key). Its purpose is to ask the user whether to proceed with deleting any deletable rows or columns that are selected. An application should not call this function, but may override the default method in order to customize the manner in which the user is asked for confirmation, or even to suppress the delete key behavior altogether.
grid-widget is the grid-widget that has the keyboard focus when the delete key is pressed. selected-subsections is a list of any grid-rows and grid-columns of the grid that are both deletable and selected. The method should return true if all of the selected-subsections should be deleted, and nil if not.
The default method shows a warning dialog if selected-subsections is the empty list, and otherwise shows a modal dialog with a generic message asking the user whether to proceed with the deletion. Here is the default method:
(defmethod confirm-grid-subsection-deletion ((grid-widget grid-widget)
selected-subsections)
(if* selected-subsections
then (y-or-n-dialog "Delete rows and / or columns ~a ?"
(mapcar #'name selected-subsections))
else (pop-up-message-dialog
(window grid-widget) "Nothing to Delete"
"There are no selected and deletable rows or columns to delete."
warning-icon "~OK")
nil))All interactive deletion could be suppressed (even if rows and columns are selectable for other purposes) by simply always returning nil from this function.
The calling of this generic function is never suppressed by adding custom cell-key-down methods. It could be suppressed by overriding the default virtual-key-down method for the grid-drawing-pane of the window of the grid-widget, though this would be modifying the keypress behavior of the grid at a low level.
See also select-subsection, deselect-subsection, and deletable.
Function, cg package
Arguments:
Returns whether the web browser will prompt the user for exit confirmation when they attempt to close the web browser tab or reload the page. The setf of this function can be called at run time to establish whether the web browser will do that for the rest of the current session. The default value is nil. Setting it to true can avoid losing unsaved changes in the CG app. This function has an effect only in CG/JS mode.
The default value for the generated application of a project can be set with the Confirm Exit widget in the CG/JS tab of the Project Manager in the IDE. The default value for the IDE can be set with the query-web-browser-exit IDE option. Those defaults can be overridden at startup time with the --confirm-exit command line argument.
(setf (confirm-web-browser-exit) t) ;; avoid losing changesGeneric Function, cg package
Arguments: configuration
Returns the value of the conserve-indentation property of configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
If the value of this property is true, the indentation style (of Lisp code entered in an Editor buffer) will be closer in style to the style used in Emacs generally (but not in the IDE Emacs editor mode). Note that exceptions can be made for individual operators in the IDE editor by calling (setf text-edit-indentation) on the desired operators. Note that operators whose names begin with strings such as "with-", "do-", and "def-" indent more closely regardless of the value of this property.
When this property is nil, arguments on successive lines will be left-justified with a first argument that is on the same line as its operator, unless an indentation style has been established for the particular operator with a call to (setf text-edit-indentation) or the operator begins with certain strings such as "with-", "do-", or "def" that always indent more closely. This default matches indentation in the Emacs editor. Setting this property to true causes successive lines to always indent more closely.
The value of this property may be set with setf with a form like
(setf (conserve-indentation (configuration *system*)) [new-value])The value can also be set by checking the appropriate box on the Editor of the Options dialog.
Function, cg package
Arguments:
This function exists only on the Windows platform.
Returns the handle of the Allegro console window if it exists, and otherwise returns nil. The console window is not a Common Graphics window, but Windows API functions could be called directly on this handle if desired.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
Function, cg package
Arguments:
This function exists only on the Windows platform.
Returns true if the Allegro CL console window exists and is currently visible, and otherwise returns nil.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
Function, cg package
Arguments:
This function exists only on the Windows platform.
Returns the string that is currently displayed in the Allegro console window's title-bar, if the console window exists, and otherwise returns nil.
The setf of this function may be called to change the console's title. The value must be a string. Nothing will be done if the console window does not exist.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
(setf (console-title) "Console for Debugging")Function, cg package
Arguments:
This function exists only on the Windows platform.
Returns the handle (an integer) for the icon that is currently displayed in the system tray for the Allegro CL console window, if the console window exists and it has a tray icon, and returns nil otherwise. (setf console-tray-icon) may be called to change the icon displayed in the tray.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
(setf (console-tray-icon) application-icon)See application-icon.
Function, cg package
Arguments:
This function exists only on the Windows platform.
If the Allegro CL console window exists and it has a tray icon and the tray icon's tooltip value has been set by a call to (setf console-tray-tooltip), then console-tray-tooltip will return that value, and otherwise it returns nil. (The default tooltip that was initially embedded is not known.)
(setf console-tray-tooltip) may be called to change the tooltip of the console's tray icon. The value may be a string to display or else nil to remove the tooltip entirely. Nothing is done if the console window does not exist.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
Generic Function, cg package
Arguments: texture
Returns a value that specifies the pixels that form the image of a pixmap. The value may be set either by calling (setf contents) or by passing the :contents initarg to make-instance when creating the pixmap.
pixmap should be a pixmap object. See cg-pixmaps.html for an overview of pixmap functionality.
The value returned by contents or passed to (setf contents) is a list of lists, where each inner list represents a row of the pixmap and each member of an inner list represents a pixel in that row. Each row member should be an index into the pixmap's colors vector, to make the pixel display the color at that index. (An exception is that if the pixmap has a mask, then any transparent pixels should be zero in the contents.)
The number of inner lists reflects the number of rows in the pixmap, and the number of members in each inner list (these should all be the same) reflect the number of columns. The width, height, and bits-per-pixel properties of a pixmap will be derived automatically from the contents if needed.
The pixels of a pixmap may alternately be specified either by specifying the texture property.
Here is how the :default-leaf pixmap (used by outline widgets) is created. This pixmap also uses the default colors from default-pixmap-color-vector.
(cache-pixmap
(make-instance 'pixmap
:name :default-leaf
:contents
'((15 15 15 15 15 15 15 15 15 15 15 15 15 15 15 15)
(15 15 0 0 0 0 0 0 0 15 15 15 15 15 15 15)
(15 15 0 15 15 15 15 15 0 0 15 15 15 15 15 15)
(15 15 0 15 15 15 15 15 0 15 0 15 15 15 15 15)
(15 15 0 15 15 15 15 15 0 15 15 0 15 15 15 15)
(15 15 0 15 15 15 15 15 0 15 15 15 0 15 15 15)
(15 15 0 15 15 15 15 15 0 0 0 0 0 0 15 15)
(15 15 0 15 15 15 15 15 15 15 15 15 15 0 15 15)
(15 15 0 15 15 15 15 15 15 15 15 15 15 0 15 15)
(15 15 0 15 15 15 15 15 15 15 15 15 15 0 15 15)
(15 15 0 15 15 15 15 15 15 15 15 15 15 0 15 15)
(15 15 0 15 15 15 15 15 15 15 15 15 15 0 15 15)
(15 15 0 15 15 15 15 15 15 15 15 15 15 0 15 15)
(15 15 0 15 15 15 15 15 15 15 15 15 15 0 15 15)
(15 15 0 0 0 0 0 0 0 0 0 0 0 0 15 15)
(15 15 15 15 15 15 15 15 15 15 15 15 15 15 15 15))))Generic Function, cg package
Arguments: &optional return-symbol-value
Returns meta-key when the user is on a Mac or control-key otherwise. In CG, the symbol meta-key refers to the Command key on a Mac. If return-symbol-value is true then the symbol's value is returned, and otherwise the symbol itself is returned.
In CG/JS mode, the returned value reflects the platform where the web browser is running, rather than where the CG Lisp application is running, which may be different when the CG app is running in server mode.
This function may be convenient when defining the event-synonym of a menu-item, when the Command key is used on a Mac and the Control key on Windows and Linux, and that is the only difference. For example:
(make-instance 'menu-item
:value 'paste-command
:title "~Paste"
:event-synonym (list (control-or-command-key) #\V))Generic Function, cg package
Arguments: texture x y
Returns (or sets with setf) the value of the pixel at row x and column y of a texture or a pixmap. The pixel at zero, zero is the top-left pixel.
As noted, contents-ref is setf'able. It is recommended that you use setf and contents-ref rather than contents-set.
Generic Function, cg package
Arguments: texture x y value
Sets the value of the pixel at row x and column y of a texture or a pixmap. The pixel at zero, zero is the top-left pixel.
Note that the related contents-ref is setf'able. It is recommended that you use setf and contents-ref rather than this function.
Generic Function, cg package
Arguments: owner-window dialog-item-or-window
This generic function is called whenever the user presses the F1 key, typically to receive context-sensitive help. It is also called if the user clicks the question mark button on the title-bar of a window that has been given the help-button property, and then clicks a dialog-item or child window in the window that has the question mark button. An application can add context-sensitive-help methods in order to handle these gestures and present help to the user.
The built-in Common Graphics methods do nothing, though the Tools | Options dialog in the IDE has the help-button property and implements a context-sensitive-help method to show HTML help on the configuration option represented by the selected widget.
When F1 is pressed, owner-window will be the owner window or screen of the window that currently has the keyboard focus. If the focus is in a dialog-item's widget-window or lisp-widget-window, then dialog-item-or-window will be that dialog-item object (rather than its window); otherwise dialog-item-or-window will be the actual child window that has the keyboard focus.
When the question mark button is used instead, owner-window will be the owner window or screen of the dialog-item or child window on which the user clicks. If the user clicks on a dialog-item of the window that has the question mark button, then dialog-item-or-window will be that dialog-item object (rather than its window); otherwise dialog-item-or-window will be the actual child window that the user clicks. (After clicking the question mark button, if the user then clicks somewhere other than on a dialog-item or child window of the window that has the question mark button, or presses the Escape key, then the operation is cancelled and context-sensitive-help is not called.)
The owner-window is intended to be useful for specialization, so that the individual dialog-items or child windows do not all need to be subclassed.
If the F1 key is also handled as an event-synonym of a menu-item, or is handled by a virtual-key-down method, or is a global keyboard accelerator (see add-global-keyboard-accelerator), then that behavior is done in addition to context-sensitive-help being called, rather than one overriding the other.
Due to operating system design, it is unfortunately not possible to tell which action the user performed (either pressing F1 or using the question mark button).
Also due to operating system design, it is not possible to use the help-button property along with the minimize-button or maximize-button property; if both are specified or defaulted, the window will show the help button but will not be given the minimize or maximize buttons.
See cg-application-help.html for various ways of displaying help in an application.
Generic Function, cg package
Arguments: window top-item format
Use of this function is deprecated. Use (setf clipboard-object) instead.
Copies top-item to the Windows clipboard directly, without affecting the Lisp clipboard stack. window should be (development-main-window \*system\*). format in theory allows you to specify the format of the object being placed, but only text format is supported in this release, so format should simple be t.
See cg-clipboard.html.
Generic Function, cg package
Arguments: window
Use of this function is deprecated. Use clipboard-object instead.
Returns the text value from the Windows clipboard directly, without affecting the Lisp clipboard stack. window should be (development-main-window \*system\*).
See cg-clipboard.html.
Generic Function, cg package
The symbol naming this operator has been moved to the dde package. Please see convert-returned-dde-buffer.
Generic Function, cg package
The symbol naming this operator has been moved to the dde package. Please see convert-returned-dde-string.
Function, cg package
Arguments: box
Returns a copy of box. Boxes are created with make-box.
Generic Function, cg package
Arguments: window
Sets the global variable *copied-character-format* to a character-format instance reflecting the character format of the character just before the current text cursor position in window. window must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
The Edit | Copy Format command on the rich edit menubar calls this function. (Note: that command does not appear on the Allegro CL Edit menu.)
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: window-or-widget
Retrieves an object from the specified window or widget and places it onto the clipboard. Returns the object that was copied and its clipboard format as two values, or the single value nil if no copy was done.
This is largely a convenience function that combines other exported functionality as it is typically used. An application menu command could call this function directly.
window-or-widget should an instance of the basic-pane, dialog-item or screen class or one of their subclasses.
The default copy-command and cut-command methods are shown below, in case you need to use some variation of this typical behavior. These methods first pass the action down to the bottom-most selected-window of the window that was passed in. Then they call either copy-selection or cut-selection to retrieve the object from the window or widget, and then call push-lisp-clipboard to add the object to the Lisp clipboard (a stack of arbitrary Lisp objects) as well as the system-wide clipboard of the underlying window system.
(defmethod copy-command ((stream cg-stream))
(let* ((child (selected-window stream)))
(if* child
then (copy-command child)
else (copy-or-cut-command stream nil))))
(defmethod cut-command ((stream cg-stream))
(let* ((child (selected-window stream)))
(if* child
then (cut-command child)
else (copy-or-cut-command stream t))))
(defun copy-or-cut-command (stream cut?)
(setq stream (or (dialog-item stream) stream))
(let* ((object (if cut?
(cut-selection stream)
(copy-selection stream))))
(and object
(let* ((format (clipboard-format-from-object object)))
(with-object-locale (stream)
(push-lisp-clipboard format object))
(values object format)))))There are also methods on dialog-item that simply pass the action to the widget's window when the widget is on a parent window.
A subtle point about the above code: The function dialog-item is called on the window so that cut-selection or copy-selection is called on a widget before being called on its associated window. This allows an application to specialize added methods on a dialog-item subclass rather than on a widget-window subclass, which would require subclassing both classes and linking them with a widget-device method.
Also, clipboard-format-from-object is called to find the appropriate format for the copied object on the underlying windowing system's clipboard.
The call to with-object-locale would be needed only in unusual cases where an application uses different locales in different widgets.
See cg-clipboard.html.
Generic Function, cg package
Arguments: stream &optional (result-context (make-graphics-context stream))
Returns a graphics-context object that stores the current drawing style options of stream. stream should be a cg-stream.
The graphics-context can later be given to the same or another stream to resume using the saved drawing style options. The specific values saved are foreground-color, background-color, font, line-width, line-dashing, line-end, line-join, line-texture, fill-texture, background-texture, current-position, and stream-origin.
If a graphics-context is passed as the result-context argument, then this object is filled in and returned. Otherwise a new graphics-context is created and returned. (You create a graphics context object with make-graphics-context. Pass the same stream to that function as was passed as the first argument to this function.)
See also set-graphics-context, graphics-context-p, and restoring-graphics-context.
Generic Function, cg package
Arguments: menu-item
Returns a copy of the argument menu-item. A specific menu-item can only be only placed on one menu so use this function to create copies of menu-items you want on more than one menu.
Generic Function, cg package
Arguments: stream texture texture-info to-box-or-position from-box-or-nil paint-operation
Implements the bit block transfer operation, generalized to pixels. Pixels from texture are copied onto stream using paint-operation to combine them with the existing ones. Note that the function copy-to-stream does much the same thing as this function and does not require the use of separate texture and texture-info objects.
from-box-or-nil is either a box object or nil. If it is a box, it is the box in texture from which copying occurs. If it is nil, then the whole pixmap is copied.
to-box-or-position is either a box object or a position object. If it is a box, it is the box in stream which is modified. If it is a position, then the pixmap is copied with its upper-left corner at that position without stretching the pixmap.
Thus, if from-box-or-nil is nil and to-box-or-position is a position, then the entire pixmap is drawn at the specified position without stretching it.
The box to be copied is intersected with the texture dimensions and stream clipping box and the resultant box is the set of pixels actually copied. If texture is a bitmap, 1's are copied as stream's foreground color, 0's as its background color. If texture-info is nil, one that matches the stream is used.
When the destination area (to-box-or-nil) is a box of a different size than the source bitmap, the copied area is stretched rather than clipped to make it fit the destination area. Clipping is performed when the source area (from-box-or-nil) is a box of a different size than the source bitmap.
Function, cg package
Arguments: filename &optional stream position
This function reads a pixmap file and copies the image to stream. stream should be a cg-stream. This function may be useful for displaying many large pixmaps without the overhead of creating Lisp representations of each pixmap, since the pixels are transferred directly from the file to the stream without creating any Lisp array to store them in. No pixmap object is created, so the individual pixels cannot be examined in Lisp (except by calling pixel or pixel-x-y to ask the stream for its pixel values).
filename is a pathname or path namestring indicating the file to read the pixmap from. This file should be either a .bmp (device-independent bitmap), .ico (icon), or .cur (cursor) file.
stream is either a window, a bitmap-stream, a printer stream, or nil. It indicates the stream to draw the pixmap on. If nil, a bitmap-stream is created and used. If the pixmap is to be used in multiple places or at multiple times in the interface, it may be useful to call this function once to store the pixmap on a bitmap-stream, and then copy the image from there to a window with copy-stream-area whenever needed.
position is a position or nil, indicating where to position the upper left corner of the pixmap on stream. If nil, the image is positioned in the upper left corner of the stream.
Two values are returned:
the stream that was passed in or created,
a texture-info containing the dimensions, depth, and colors of the pixmap.
Note that if stream is a bitmap-pane, then the image is copied to the backing store of the window but not to the visible window itself. The image may then be viewed at any time by calling invalidate on the window. This allows loading a new pixmap into the window while the end user is still viewing the previous pixmap, and then to very quickly switch to the new pixmap when the user is ready.
Function, cg package
Arguments: to-stream texture texture-info to-box-or-position from-box-or-nil mask-texture
This function is similar to copy-pixels-to-stream except it allows you to copy a non-rectangular image. This is done by passing a mask-texture. The texture defines which pixels should be copied and which should be left unchanged.
The first five arguments are the same as for copy-pixels-to-stream. The sixth argument is mask-bitmap, a 1-bit-per-pixel texture with a 1 wherever the texture should be transparent (destination is left alone) and a 0 wherever texture should modify the destination. This function works by erasing the destination wherever there is a 1 in mask-texture and then merging in texture with the paint operation. (Since the operation is predefined, there is no paint-operation argument.)
If you use load-pixmap to load a .ico (icon) file, the third returned value is a mask bitmap suitable for using as the mask-texture argument.
Function, cg package
Arguments: pos
Returns a copy of the argument position.
Generic Function, cg package
Arguments: window-or-widget
Returns an object from the specified window or widget that is suitable for placing onto the clipboard, or nil if no suitable object is found. This function is called by copy-command, which does the actual placing of the object onto the clipboard. An application could call either function, or add methods to either in order to extend the clipboard functionality.
window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass.
If a copy was done, then a second value is returned that indicates the clipboard format that is appropriate for the copied object on the underlying platform's system-wide clipboard. This will be one of the keywords :text, :rich-text, or :pixmap. The Windows clipboard knows how to hold one value of each of its clipboard formats simultaneously.
The default method returns the object returned by calling selected-object, plus :text as the second value. The methods for bitmap-pane and drawable-pane return a pixmap that is created by calling get-pixmap on the window, plus :pixmap as the second value. The method for rich-edit-pane returns the selected text as a rich text string, plus :rich-text as the second value. The method for dialog-item simply calls copy-selection on the window of the dialog-item if the widget is currently on a parent window.
An anomaly: When called on a rich-edit-pane in Windows, it is copy-selection rather than copy-command that actually places the object onto the clipboard. This is due to a problem with mapping the Common Graphics behavior onto the Windows clipboard and rich-edit APIs. In this case, both the rich text string and the plain text string are placed onto the clipboard, with the rich text string being topmost on the Lisp clipboard stack.
An application could add methods for additional widget or window classes if you would like to call copy-selection (or copy-command) on the selected widget or window without regard to its class, letting it handle the command if it knows how. To do this for a widget (rather than a window), you could specialize on the dialog-item subclass if you will only call copy-selection on the widget; if you might instead pass the widget's associated window, then you would need to specialize on the widget-window subclass. Doing so requires subclassing both the dialog-item class and the widget-window class, and associating the two subclasses together with a trivial widget-device method.
cut-selection does what this function does and also deletes the returned object from the window or widget. See also paste-selection.
In releases prior to 7.0, this function passed its action to the lowest selected descendent child window of the specified window, though some applications may not desire such automatic redirection. The functions focus-component, get-focus, or selected-window may be useful for finding a suitable widget or window to pass to this function. Earlier releases also returned the window where the copy was actually done as the first value, and the copied object as the second value.
See cg-clipboard.html.
Generic Function, cg package
Arguments: to-stream from-stream to-box from-box paint-operation
Like copy-pixels-to-stream but copies pixels from from-box of from-stream to to-box of to-stream. The texture used in copying is the fill texture of the to-stream. to-stream and from-stream should be cg-streams.
Generic Function, cg package
Arguments: pixmap-or-cursor stream &optional to-box-or-position from-box-or-nil (mode po-replace) alpha
Copies a pixmap object or a mouse cursor object to stream. stream should be a cg-stream. This function replaces the older function copy-pixels-to-stream, which required the use of separate texture and texture-info objects.
If from-box-or-nil is a box, this function copies the from-box-or-nil portion of pixmap-or-cursor to the to-box-or-position portion of stream, using a particular pixel-combination mode. If from-box-or-nil is nil, the whole pixmap or cursor is copied.
If to-box-or-position is a box, the pixmap-or-cursor is copied to that box and is stretched (if necessary) as with copy-pixels-to-stream. If to-box-or-position is a position, then the pixmap or cursor is copied without stretching so its upper left corner is at the position. If to-box-or-position is nil (the default), then the pixmap or cursor is copied without stretching to position 0,0 of stream.
If pixmap-or-cursor has a mask texture, then copy-pixels-with-mask-to-stream is called internally in order to use it. Otherwise copy-pixels-to-stream is called internally. If pixmap-or-cursor has a pixmap-handle, then that is used for drawing the pixmap, and otherwise the pixmap's texture is used.
mode may be any value that is valid as the paint-operation of a stream. copy-to-stream always uses the value of this mode argument, rather than using the stream's current paint-operation as other drawing functions do. The default value is po-replace. See paint-operation for more information on the various choices.
The alpha argument is used only on Windows, and only when the variable *alpha-blending* is true. It can create translucent effects where the existing background partly "shows through" the pixmap that is being displayed. Its value should be either nil or an integer between 0 and 255 inclusive. If 255, nil, or unspecified, the pixmap will be drawn with full opacity. Otherwise the value specifies the amount of opacity, where 0 would make the pixmap completely transparent and unseen (not useful), and where for example 192 would let the previous background show through by one-fourth. See the variable *alpha-blending* for more information.
Instead of passing a pixmap object, you can alternately pass either a cursor object, a pixmap handle, or a symbol that is bound to a pixmap, cursor, or pixmap handle. copy-to-stream will not work on a cursor object if calling texture on it returns nil, as is the case with several cursors supplied by the operating system, because Common Graphics does not have the pixel array to copy.
To fill an area by tiling a pixmap rather than by stretching it, call replicate-pixmap instead.
For an overview of pixmaps, see cg-pixmaps.html.
Function, cg package
Arguments: filename
This function is specific to the Windows platform, and will always return 1 elsewhere. On other platforms, pixmaps can be used where icons are used on Windows.
Returns a non-negative integer indicating the number of icons in the file filename. Zero is returned if the file does not exist, is of some other type, or if no icons are in the file. filename should be a string indicating a file with a .ico, .dll, or .exe extension.
See cg-icons.html.
Function, cg package
Arguments: pixmap
This function is specific to the Windows platform, and will have no effect elsewhere. On other platforms, pixmaps can be used where icons are used on Windows.
Returns an icon handle, which can be used as the icon of a window's titlebar, or as the pixmap-icon property of controls that display pixmaps or passed to copy-to-stream or copy-pixels-to-stream. The pixmap object should contain a mask in addition to the usual texture.
An icon handle is like a pixmap handle (a handle to a device-dependent pixmap that resides in the OS) that has a mask built in, so that the background color or whatever was drawn before the icon can show through the icon.
See also extract-icon-from-file, for creating icons from Windows icon files rather than from Common Graphics pixmaps.
See cg-icons.html.
Generic Function, cg package
Arguments: stream texture texture-info
Creates a device-dependent pixmap and returns a handle to it. The pixmap will contain the correct colors for drawing on stream using stream's current palette. stream should be a cg-stream.
This function is largely for the backward compatible style of using separate objects for the texture, texture-info, and pixmap handle. It is now recommended to instead use a pixmap object, which encapsulates all of these. With a pixmap, call open-pixmap-handle to cause the pixmap to use a handle to a device-dependent pixmap rather than passing its array of pixels each time it is drawn.
Generic Function, cg package
Arguments: basic-pane
Returns the Lisp process that called make-window to create the argument basic-pane (which is typically a window).
This function may be useful for managing windows in multiple processes, due to certain considerations that are good to keep in mind when multiple processes create windows. For example:
Killing a process (such as by calling process-kill) will always close all of the windows that were created by that process.
User keyboard and mouse events that occur on a window (and other messages that are programmatically sent to the window) will run code in the process that created the window.
When calling CG functions on this window later, the safest approach is to always do that in the creation process of the window. See post-funcall-in-cg-process for details.
Miscrosoft Windows Note: Creating a single window hierarchy that contains windows created in multiple processes is likely to lead to messaging timeouts or hangs when a window in one process sends a message to a window in another. (One reason is that the operating system combines the message queues of the multiple processes in this case.) This arrangement should be avoided when feasible. This does not apply to CG/JS mode in the Windows operating system.
While an application could maintain its own record of which process created each window, calling creation-process may be more convenient. See About using multiple windowing threads in a Common Graphics application in cgide.html.
Function, cg package
Arguments: grid-widget row-or-row-section column-or-column-section &optional include-border-p box
Returns a box for the intersection of a grid-row or grid-row-section with a grid-column or grid-column-section. The box excludes any parts of the sections or subsections that are currently scrolled out of view.
When the specified cross-section is scrolled completely out of view, this function returns nil.
grid-widget is the grid-widget itself.
row-or-row-section is either a grid-row or a grid-row-section.
column-or-column-section is either a grid-column or a grid-column-section.
If include-border-p is true, then the area occupied by the border lines at the right and bottom edges of the cross-section is included in the returned box. Otherwise it is excluded.
box may be either a box (see make-box) or nil. If a box, then that box is modified and returned. If nil, a new box object is created and returned. Passing a scratch box avoids consing one that must be garbage collected.
See also section-box and invalidate-section.
Generic Function, cg package
Arguments: hotspot-mixin
Returns the hotspot that is currently under the mouse in the hotspot-mixin window, or nil if none.
Generic Function, cg package
Arguments: object-editor
Returns the particular instance that an object-editor is currently displaying, if any, or else returns nil. An application should not modify this property. To display an arbitrary instance call display-instance instead.
Generic Function, cg package
Arguments: stream
Returns an integer indicating the current line where selected text starts or, if there is no selected text, where the text cursor is located. 0 indicates the first line. stream can be a multi-line-editable-text control. It can also be a text-edit-window or text-edit-pane.
See also current-text-column.
Function, cg package
Arguments: graphical-stream
Returns the current position of the specified graphical-stream, from which lines and text may be drawn. Unlike ncurrent-position, this function always creates the position object to return. See ncurrent-position for more information.
Function, cg package
Arguments: graphical-stream
Returns the X coordinate of the current position of the specified graphical-stream, from which lines and text may be drawn. See ncurrent-position for more information.
Function, cg package
Arguments: graphical-stream
Returns the Y coordinate of the current position of the specified graphical-stream, from which lines and text may be drawn. See ncurrent-position for more information.
Generic Function, cg package
Arguments: stream
Returns an integer indicating the current text column where the selected text of stream begins or, if there is no selected text, where the text cursor is located. Zero indicates the leftmost text column.
stream can be a multi-line-editable-text control, a text-edit-window, or a text-edit-pane.
See also current-line-number.
Generic Function, cg package
Arguments: window-or-dialog-item-or-hotspot
Returns the current mouse cursor of window-or-dialog-item-or-hotspot, which determines the appearance of the mouse cursor whenever it is inside that window (see basic-pane), widget (see dialog-item), or hotspot.
Calling (setf cursor) will set the current mouse cursor. An alternative is to call (setf cursor-name).
The value may be either an instance of the cursor class or a "cursor handle" that is the value of one of the built-in mouse cursor variables such as cross-cursor.
A cursor handle in CG/JS mode is a string that JavaScript uses as the name of the cursor, while in Windows desktop mode it is an integer. In CG/JS you could specify a JavaScript mouse cursor name that is not one CG's standard choices, such as "grab" for a hand that is grabbing rather than pointing, from Mozilla's list.
The value may also be nil, which for a window means to remove the mouse cursor completely when it is inside the window, and for a widget means to use the default cursor for that widget, which is usually the arrow cursor. For a hotspot, nil means to use the parent window's cursor.
The value may also be the keyword :default, which means to use the default cursor for either a window or a widget. The default value is :default for a window and nil for a widget or hotspot. The default cursor image is typically an arrow cursor (see arrow-cursor).
The mouse cursor of a window is used only in the interior of the window, and it is not possible to set the cursor for the frame area of a window. Similarly, certain areas of some controls, such as the column headers of a list-view control or the body of a tab-control, are not customizable and will not show the custom cursor that is assigned to the control.
To use different mouse cursors in different areas of a single window's interior, you can write a mouse-moved method that specializes on the window's class and which calls (setf cursor) on the window, passing a different cursor depending on the cursor-position argument that was passed to mouse-moved. Alternately, you could write a cursor method that returns a different cursor based on the value returned by a call to ncursor-position or cursor-position.
See the section on mouse cursors in cg-pixmaps.html for more infomation.
Generic Function, cg package
Arguments: cursor
Returns the cursor handle of cursor if it has one, or else nil. cursor should be a cursor instance.
There is probably no need to call this function, because either a cursor handle or a cursor object can be passed to (setf cursor).
Generic Function, cg package
Arguments: object
Returns the name of the mouse cursor of object if it has one, or else nil. object may be a window, a widget (dialog-item), or a hotspot.
The setf of this function can be called to set the cursor of an object from its keyword name, rather than from the cursor instance or its cursor-handle. See the section on mouse cursors in cg-pixmaps.html.
Function, cg package
Arguments: window-or-screen
Returns the current mouse cursor position within window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*.
CG/JS Note: In CG/JS mode, this will return a zero-zero position if the mouse has not yet been moved after the application has started up, because CG can know the position only from mouse movement messages.
The setf of this function may be called to move the mouse cursor programmatically. This may be useful, for example, for moving the mouse cursor to the center of an object that the user is about to drag. On the other hand, such programmatic moves can be annoying to a user with a physical (rather than a touch) mouse because such a user might have to lift the physical mouse in order to once again make the the physical mouse's range of movement match the mouse cursor's range on the screen. (If the physical mouse is near the edge of the desk and the cursor jumps to the top of the screen programmatically, the user cannot bring it back to the bottom without lifting the mouse and repositioning it on the desk.)
See also ncursor-position.
Generic Function, cg package
Arguments: stream
Returns two values, which are the width and height (in pixels) of mouse cursors on the platform being used. When creating a custom mouse cursor from a texture (see the section on Mouse Cursors in cg-pixmaps.html), the texture should be this size.
See also fill-texture.
Generic Function, cg package
Arguments: configuration
Allows overriding the system default status-bar font. The value should be either a font object or nil to use the system default font. This applies to standalone applications as well as the IDE.
Generic Function, cg package
Arguments: configuration
Allows overriding the system default tooltip font. The value should be either a font object or nil to use the system default font. This applies to standalone applications as well as the IDE.
Generic Function, cg package
Arguments: window-or-widget
Deletes an object from the specified window or widget and places it onto the clipboard.
This function behaves just as copy-command does, except that it calls cut-selection rather than copy-selection so that the copied object is also removed from the window if possible. See copy-command for more information.
See cg-clipboard.html.
Generic Function, cg package
Arguments: window-or-widget
Returns an object from the specified window or widget that is suitable for placing onto the clipboard, or nil if no suitable object is found. Also deletes the returned object from the window or widget when it knows how to do so. This function is called by cut-command, which does the actual placing of the object onto the clipboard. An application could call either function, or add methods to either in order to extend the clipboard functionality.
window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass.
If a cut was done, then a second value is also returned to indicate the suitable clipboard format, as described under copy-selection.
The default method just calls copy-selection, and so does not delete the copied object. The methods for editable-text-pane and text-edit-pane return and delete the selected text, if any. The method for rich-edit-pane returns a rich text string for the selected text if any, and deletes the text. The method for combo-box returns and deletes the selected text if its typable property is true, and otherwise does nothing and returns nil.
The methods for single-item-list-pane and multi-item-list-pane will return the selected item or items and also delete them from the range of the associated dialog-item. The method for dialog-item simply calls cut-selection on the window of the dialog-item if the widget is currently on a parent window. See copy-selection for a note abouting adding additional methods for other types of widgets.
An around method on widget-window causes nothing to be done if window-or-widget is either a dialog-item or its associated window, and the widget's cuttable property is nil. By default, CUTTABLE is true only for text-editing widgets.
An anomaly: When called on a rich-edit-pane in Windows, it is cut-selection rather than cut-command that actually places the object onto the clipboard. This is due to a problem with mapping the Common Graphics behavior onto the Windows clipboard and rich-edit APIs. In this case, both the rich text string and the plain text string are placed onto the clipboard, with the rich text string being topmost on the Lisp clipboard stack.
In releases prior to 7.0, this function passed its action to the lowest selected descendent child window of the specified window, though some applications may not desire such automatic redirection. The functions focus-component, get-focus, or selected-window may be useful for finding a suitable widget or window to pass to this function. Earlier releases also returned the window where the copy was actually done as the first value, and the copied object as the second value.
See cg-clipboard.html.
Generic Function, cg package
Arguments: *dialog-item *
Returns whether anything will be done when cut-selection or delete-selection is called on dialog-item or its widget-window. The value of this property may be set by calling (setf cuttable), or it may be set in the inspector when laying out forms in the IDE.
If nil, then cut-selection or delete-selection will do nothing and will return nil. Otherwise they will proceed as usual (though deletion is still done only when there is an applicable method to do it).
The default value is t for text-editing widgets, where text deletion is typically allowed, and nil most everywhere else. The default is t for a combo-box, though this applies only when its typable property is true and affects only the typable pane. The value may be set to true for a single-item-list or multi-item-list to cause cut-selection and delete-selection to remove the selected item(s) from its range.
See also pastable and cg-clipboard.html.
Generic Function, cg package
Arguments: grid-row
Returns the arbitrary object from the application that is being represented by this grid-row. Typically, a data-object is assigned to a grid-row by passing the :data-object initarg to make-instance when creating the grid-row. draw-cell methods then often call data-object to retrieve values from the object to display in various cells.
For example, in the employee grid example the data-object of each grid-row is an instance of the "employee" class. These employee instances are completely independent of any user interface for them, and contain the real-world data for each employee. Whenever the grid wants to display some attribute of an employee in a grid-cell, it calls the grid-column's data-reader function on the grid-row's data-object to retrieve the needed real-world information from the employee object. The employee grid example can be found on the Examples tab of the Navigator dialog.
data-object is a property of the grid-row and column-header-row classes.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: grid-column
Returns the function that converts the programmatic value returned by this grid-column's data-reader function into the actual value that is displayed in a grid cell. This is similar to the on-print property of many controls. Typically the function returns a formatted string, but may return other sorts of values for grid-columns that represent data with non-strings (such as the bar-chart in the employee grid example). The employee grid example can be found on the Examples tab of the Navigator dialog.
The function should take a single argument, which is an arbitrary data-object attribute value.
For example, in the employee grid example, the Department column's data-reader is employee-department, which is simply the reader method for the department slot of an employee instance. When called on an employee instance, this function returns a symbol like :marketing. This symbol is fine for representing the department programmatically, but to display it nicely in a grid cell, the Department grid-column has the data-read-converter "capitalize-if-symbol", which is a function that takes the symbol :marketing and returns the string "Marketing" to display in the grid cell.
A special case is that the values that appear in the drop-down list of a combo-box-column-mixin cell are formatted by the on-print function of the grid-column even though the value appearing in the grid cell itself is formatted by the column's data-read-converter function as with other grid cells. To use the same formatting in both places, specify the same function for each of these properties.
NOTE: Your application does not call the data-read-converter function; it supplies the data-read-converter function which is then called automatically by the system as needed.
See the spreadsheet-value-printer function for an example of how a data-read-converter function converts data that the grid-widget reads from somewhere into the strings that it displays in grid cells.
data-read-converter is a property of the grid-column and row-header-column classes.
Generic Function, cg package
Arguments: grid-column
Returns (or sets with setf) a function that retrieves the value to be displayed in a grid cell. This function is called by the default read-cell-value method, and supplying a data-reader function and a data-object function is an alternative to writing your own read-cell-value method. The data-reader may be nil if this facility is not used. The default value is nil.
The data-reader function is a property of a grid-column, and is called once for each grid-row that intersects that column to find the value to be displayed in the cell at that intersection. The function should take a single argument, which is the grid-row's data-object. The function is typically simply the reader function of the data-object for the attribute represented by this grid-column. If this column is accessing a slot that has no writer function or the writer function is not known, then the data-slot property could be used instead.
For example, in the employee grid example, each row represents an employee, and the Department column represents the department attribute of each employee. The data-reader function of the Department column is employee-department, which is simply the reader method for the department slot of an employee instance. To find the value to represent in the Department column for each employee, the Department column's data-reader function (employee-department) is called on the data-object (an employee) of each grid-row. The employee grid example can be found on the Examples tab of the Navigator dialog.
NOTE: Your application typically will not call the data-reader function, and instead will supply the data-reader function which is then called automatically by the system as needed. Specifically, the built-in column classes such as editable-text-column-mixin will call the data-reader whenever they draw a cell, and a custom draw-cell method that an application supplies may call the default read-cell-value method, which calls the data-reader. Otherwise the draw-cell method may use some custom technique to find the value to draw, and a data-reader method is not needed at all.
data-reader is a property of the grid-column and row-header-column classes.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: grid-column
Returns the name of a slot that holds values to be displayed in cells of a grid-column, or else nil if this property is not being used. The value may be set at creation time by passing the data-slot initarg, or any time later by calling (setf data-slot). The default value is nil.
This property will be used when reading cell values only if the default read-cell-value method is not overridden and the grid-column has no data-reader function. It will be used when writing cell values only if the default write-cell-value method is not overriden and the grid-column has no data-writer function.
If this property is used, then when a grid cell is drawn, the value to display is found by calling slot-value with the data-object of the grid-row along with this slot name. If the user interactively edits the value in a grid cell, the new value is written back into application data by calling (setf slot-value) with the data-object of the grid-row along with this slot name and the new value.
It is usually preferable to use data-reader and data-writer functions because they will trigger the usual side effects of a slot's reader and writer functions. But data-slot can be useful for slots that do not have reader and writer functions, or when these functions are not known.
A special feature of a data-slot value is that it may indirectly access a slot of an object that's stored in a slot of the grid-row's data-object. This is done by using a value that is a list of slot names rather than a single slot name. The first slot name in the list should be a slot of the grid-row's data-object, the second slot name in the list should be a slot of the object that is found in the first slot, and so on. For example, if the data-object of each grid row is a patient object, and this grid column is editing the hospital of each patient, then the column's data-slot might be the list (hospital ceo phone-number) to access the phone number slot of the object that's in the CEO slot of the object that's in the hospital slot of the patient of each grid row. A class-grid makes use of this feature internally, but an application could use it directly as well.
Generic Function, cg package
Arguments: grid-column
Returns the function that takes a value that has been entered interactively in a grid cell, and converts it into a value to be used programmatically by the application. The value returned by this function will be written to the grid-row's data-object by the grid-column's data-writer function.
The function should take a single argument, which is a value that the user has interactively entered into a cell of the grid-column that is using this function to convert user input.
A data-write-converter is typically used when the user can type a string into a grid cell, and the string needs to be converted to some other type of value for internal use. For example, in the employee grid example, the Department column's data-write-converter is make-department-symbol, which takes a department string like "Sleeping" that the user has typed into the grid cell, and converts into a keyword symbol like :sleeping, which is the internal representation of a department.
data-write-converter is a property of the grid-column and row-header-column classes.
Generic Function, cg package
Arguments: grid-column
Returns (or sets with setf) a function that takes a value that has been entered interactively into a grid cell and writes the value into the application object that is being represented in the grid cell. This function is called by the default write-cell-value method, and supplying a data-writer function and a data-object function is an alernative to writing your own write-cell-value method. The data-writer may be nil if this facility is not used. The default value is nil.
The data-writer function is a property of a grid-column, and is called whenever the user enters a value into a cell of that column. The function should take two arguments, which are (1) the value that has been entered by the user and optionally converted by the grid-column's data-write-converter function, and (2) the grid-row's data-object. The function is typically simply the writer function of the data-object for the attribute represented by this grid-column.
For example, in the employee grid example, each row represents an employee, and the Department column represents the department attribute of each employee. The data-writer function of the Department column is (setf department), which is simply the writer method for the department slot of an employee instance. If the user enters "Sleeping" in a cell of the Department column, then the Department column's data-writer function, (setf employee-department), is called on the data-object (an employee) of the grid-row that the modified cell is in. The employee grid example can be found on the Examples tab of the Navigator dialog.
NOTE: Your application does not call the data-writer function; it supplies the data-writer function which is then called automatically by the system as needed.
data-writer is a property of the grid-column and row-header-column classes.
See the grid-widget class for an overview of writing grid-widget code.
Function, cg package
Arguments: widget new-value old-value
This is the on-change function of an Add button that may be automatically created for a slot-editing-class-grid.
This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.
Function, cg package
Arguments: widget new-value old-value
This is the on-change function of a Create button that may be automatically created for a slot-editing-class-grid.
This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.
Function, cg package
Arguments: widget new-value old-value
This is the on-change function of a Delete button that may be automatically created for a slot-editing-class-grid.
This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.
Function, cg package
Arguments: widget new-value old-value
This is the on-change function of a Remove button that may be automatically created for a slot-editing-class-grid.
This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.
Generic Function, cg package
Arguments: calendar-widget
The name of the upper-left pixmap for displaying the previous page in a calendar widget. It should have the same size as the increment pixmap.
See also increment-pixmap-name, the calendar class and the function ask-user-for-date.
Macro, cg package
Arguments: ocx-object-name-string &key doc-path use-native-size toolbar-string-or-icon toolbar-after toolbar-tooltip toolbar-help-string
Defines a Common Graphics dialog-item class, and an associated widget-window class, for one of the OLE controls that was defined by a call to ole:def-ole-linkage. All such widgets will be subclasses of the ocx-widget class, and their widget-windows will be subclasses of the ocx-widget-window class. Methods for the Common Graphics classes that are created will be defined in the package that was defined by the ole:def-ole-linkage form.
A call to def-cg-ocx-control should be a top-level form in an application source code file, and should be placed somewhere after a call to ole:def-ole-linkage that loads the OLE application that defines the control. If the two forms are in the same file, you should place the ole:def-ole-linkage form inside an (eval-when (compile load eval) ...) form to ensure that that macro call is evaluated to create its new package before the def-cg-ocx-control form is macroexpanded (see the example at the bottom of this page). Compiling an OLE control can take a fair amount of time, so in an IDE project (for example) it is a good idea to place these forms in a project file by themselves, so that the control does not need to be recompiled whenever you modify other code in the same file.
ocx-object-name-string should be a string naming the particular OCX control, such as "WebBrowser" or "MonthView". Refer to the documentation for the OLE application that was loaded, or its controls, to find these names.
doc-path: if doc-path is non-nil, then it should be a pathname or path namestring for a documentation file. Compiling (or simply macroexpanding) the def-cg-ocx-control form will generate the file with brief documentation for the control's properties, methods, and event-handler callback functions. The default is nil, in which case no documenation file is created.
use-native-size: if use-native-size is true, then the widgets of this class will ask the OLE server for the natural size for the widget, given its current properties, and the widget will be sized accordingly. If nil, then the widget may be made any size, as with other widgets. You should pass whichever value is appropriate for the control being defined; for example, true is appropriate for the MonthView control, which always draws a calendar at a standard size, whereas nil is appropriate for the WebBrowser control, which works at any size. The default value is nil.
toolbar-string-or-icon: if toolbar-string-or-icon is true, and the IDE is present, then a button for the new widget class will be added to the IDE's Components toolbar to allow you to place instances of the widget class onto form windows in projects. This argument is passed to ide:add-to-component-toolbar as its pixmap-or-title argument. The default value is nil.
toolbar-after, toolbar-tooltip, toolbar-help-string: if toolbar-string-or-icon is true (and the IDE is present), these values are passed as the values of the corresponding arguments (i.e. after, tooltip, and help-string) to ide:add-to-component-toolbar.
def-cg-ocx-control will define Common Graphics properties for any OLE get and put functions that take a single argument (which is the widget itself). In the IDE inspector, you will see these properties mixed with the usual properties that are defined by Common Graphics. In a case-sensitive Lisp, the standard Common Graphics properties will be entirely lowercase, while the properties provided by the OCX control will be mixed case. Sometimes there will be two properties with the same name that differ only in string case. These symbols do not conflict, even in a case-insensitive Lisp, because the package that is created for the symbols that are provided by the OCX control never uses any other package and is never used by any other package. This is necessary because we cannot predict what symbol names an OCX control may use.
Note that you don't need to define the WebBrowser control, because Common Graphics defines it internally. It is exported as the cg.ie:cg-WebBrowser dialog-item class, though for this particular control it may be preferable to use the platform-independent subclass called html-widget.
Here is how Common Graphics defines the WebBrowser control. You should not evaluate this code because Common Graphics has already done so, but you could define some other OCX control similarly.
;; Code sample for information only. It should not be
;; evaluated by users.
;;
(eval-when (compile load eval)
(ole:def-ole-linkage #:cg.ie :application "InternetExplorer"))
(def-cg-ocx-control "WebBrowser"
:doc-path (merge-pathnames "WebBrowser.txt"
*compile-file-pathname*))See also ole.html.
Function, cg package
Arguments:
This function is used only in CG/JS mode. It returns nil by default, but the setf of this function can be called to specify a particular process that should receive events that are not associated with a window. The large majority of events are associated with a window, and those events get dispatched to the creation-process of the window. Other events will get passed to the initial CG process unless the setf of this function is called to specify some other process. Timer events in particular are not associated with any window, and there may be others.
(setf (default-process-for-events) my-process-for-windowless-events)Macro, cg package
Arguments: var &optional init (doc nil docp) even-on-virtual-threads
This macro works just like defvar, except that every CG process that's created will automatically get its own binding for the symbol. (This macro also has an additional even-on-virtual-threads parameter, but it is no longer used and is kept only for backward compatibility.)
This may be useful when enhancing an application so that it works with multiple simultaneous web browser clients. (That is allowed when the Max Clients option on the CG/JS tab of the Project Manager is greater than one.) That would not work if client-specific information is stored in global variables, so converting defvar forms to defvar-cg is a simple way to handle that particular problem.
Function, cg package
Arguments:
Returns a 256-member vector of rgb objects with the colors spread out evenly. This may be useful when Windows is running in 256-color (8-bits-per-pixel) mode in order to map a higher-resolution pixmap of unknown colors into 256 colors.
To do so, call open-palette on a window and the color vector returned by this function to create a palette for that window, then apply setf to palette to assign the palette to the window, and then call copy-to-stream to copy the high-resolution pixmap to the window. The image in the window should approximate the high-resolution pixmap about as well as can be expected with 256 colors without having additional knowledge of the particular colors used in the pixmap.
Function, cg package
Arguments:
Returns the default value for the subkey argument of the functions add-application-window, find-application-window, and remove-application-window. It is probably not useful for an application to call this function.
Now that GTK is no longer supported, the returned value is always the current process.
The idea behind the subkey argument to add-application-window was to allow windows in distinct processes to have the same name, and still allow find-application-window to find the correct window when called in event-handler callback code of windows in the same process. This works because event callback code runs in the creation-process of each window.
Generic Function, cg package
Arguments: object
Returns the default background color for object. This color will be used as the background color when the value of the background-color property is nil.
The value must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.
The built-in methods are specialized on the window class. Thus, for example, the default for dialog-mixin is returned by system-dialog-background-color and for basic-pane is returned by system-background-color.
Contrast with the built-in method for default-foreground-color, which is the value returned by system-foreground-color whatever the type of window.
Generic Function, cg package
Arguments: dialog
Returns the default-button object on dialog if dialog has a default button and returns nil if dialog does not have a default button. If dialog has more than one default-button (strongly discouraged but not impossible), one is returned but which one is not determined. See the default-button control.
Generic Function, cg package
Arguments: grid-widget-or-section
Returns whether a pseudo-three-dimensional border will be drawn around each cell in the specified grid-widget, grid-row-section, or grid-column-section. If this property is true for any of these objects that contain a given cell, then that cell will have a 3d border. The setf of this function may be called to change the 3d border, at which time the grid will be drawn as needed to display the new borders.
The above actually describes the behavior of the default cell-3d-border method. An application may supply cell-3d-border methods to override this behavior for some or all of the cells.
If the value is nil (the default), then no 3d borders will be drawn. If it is the keyword :sunken-edge, then 3d borders will be drawn that appear sunken (making the grid cells appear raised). If it is t, then 3d borders will be drawn that appear raised (making the grid cells appear sunken).
If the regular (non-3d) borders of the cells are non-zero (see border-width and default-cell-border-width) while 3d borders are turned on, then both the regular and 3d borders are drawn, with the 3d borders just inside the regular borders. 3d borders may look best without the regular borders, so it is likely desirable to set the width of the regular borders to zero when using 3d borders.
Generic Function, cg package
Arguments: grid-widget-or-section
Returns the color, if one has been specified, that will be used by default to draw the row and column borders within the specified grid-section or within all of the grid-row-sections and grid-column-sections of the specified grid-widget. The setf of this function may be called to change the color, at which time the grid will be drawn as needed to display the new color. This default may be overridden by specifying the border-color property of individual grid-row and grid-column instances.
The value may be either an RGB color object (as returned by make-rgb or ask-user-for-color), or a symbol whose global value is an RGB object, or nil. The initial value is nil. When nil, effective-border-color will find a color to use in some other way.
Generic Function, cg package
Arguments: grid-widget-or-section
Returns the width, if one has been specified, that will be used by default to draw the row and column borders within the specified grid-section or within all of the grid-row-sections and grid-column-sections of the specified grid-widget. The setf of this function may be called to change the width, at which time the grid will be drawn as needed to display the new border width. This default may be overridden by specifying the border-width property of individual grid-row and grid-column instances.
The value may be either a non-negative-integer or nil. The initial value is nil. When nil, effective-border-width will find a width to use in some other way. Zero means to draw no border at all (though default-cell-3d-border may still be used to draw a separate 3d border).
Generic Function, cg package
Arguments: window
Returns the clipboard format that will be used by default when copying, cutting, and pasting in window. The built-in methods return :text for a text-edit-pane, :rich-text for a rich-edit-pane, and :pixmap for bitmap-pane or drawable-pane. An application could conceivably add a custom default-clipboard-format method for one of its own text-edit-pane subclasses.
See cg-rich-text.html for information about rich text editing in Common Graphics. See also cg-clipboard.html.
Function, cg package
Arguments:
Returns the default pixmap to use for all of the items of an outline that have subitems when those subitems are currently hidden. The image is a closed file folder.
Generic Function, cg package
Arguments: class-grid
Returns the section-size that will be used for any new grid-columns in the body of a class-grid when no explicit size is specified for those columns. The value may be set with the default-column-width initarg or by calling (setf default-column-width).
Changing the value affects only grid columns that are created later by modifying the edited-slots property of the class-grid.
Generic Function, cg package
Arguments: project-or-app
This project property can be used to handle all unexpected errors that might be signaled in a delivered application that was generated from a project. The value of this property can be set on the Advanced tab of the Project Manager dialog, using the widget labeled Default Error Handler for Delivery.
The setf of this function may be called to set the value programmatically, though typically you would set the value interactively in the Default Error Handler for Delivery widget on the Advanced tab of the Project Manager dialog.
The value of this property should be the name of a function that accepts one argument, which will be the condition object for an error that was signaled. The default value is report-unexpected-error-and-exit, which displays a simple dialog about an unexpected error and then exits the application. An alternate built-in function is write-backtrace-to-file, for debugging a generated application that is crashing or failing to start up.
The function will be called whenever an otherwise unhandled error is signaled in the event-handling loop of an application that was generated from a project, if and only if the Enable Debugging of Runtime Errors option has been disabled on the Build tab of the Project Manager dialog (see ide:build-flags. The global variable *show-console-on-standalone-error* must also be true, as it is by default. If the function returns, event-loop will continue handling events.
To handle errors in a meaningful way, an application would typically use handler-case or handler-bind forms around small pieces of code in order to handle the particular errors that might be signaled in those places. But it may also be desirable to further trap all other unexpected errors, to allow the user to attempt to recover before exiting. Using this project property for that purpose is an alternative to wrapping general event handlers around all individual event-handling functions in a Common Graphics application, which could be very tedious.
As an example, a default error handler could call pop-up-message-dialog to report that an unexpected error has occurred, and give the user an option to let the program attempt to save their work before exiting. It could then do a save (perhaps after first doing a backup), and then call excl:exit to exit the application. The function alternately could return rather than calling excl:exit, to allow the user to continue working, though that's not recommended in this general case where the application is in an unpredictable state due to an unknown error. It could also exit the program by calling its own usual exit function (or call user-close on the main window, for example) rather than calling excl:exit, if the usual side effects are not too risky while in an unknown state.
In a generated application, this property will be on the app object rather than on a project, since the project system does not exist in a generated application. An application could change this app property at runtime if desired; it exists on the app object in the IDE as well, though it is not used there.
If an error is signaled in an application's default-error-handler-for-delivery function itself, then Lisp will simply exit, and it may not be obvious why. In particular, that can happen if the error-handling code uses functionality from a Lisp module that exists in the IDE but not at runtime. To debug that, it may be necessary to artificially call the code that's in the error-handling function in a test version of the standalone app where Enable Debugging of Runtime Errors is turned on (see the Build tab of the Project Manager dialog).
Generic Function, cg package
Arguments: window
Returns the default foreground color for window. This color will be used as the foreground color (for drawing and for text) when the value of the foreground-color property of window is nil.
The value must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.
With the built-in methods, this is always the value returned by system-foreground-color, usually black unless the end user has set up a different text color in the Windows Control Panel.
Contrast with default-background-color, which has different defaults for various window classes, such as system-dialog-background-color for dialog-mixin and system-background-color for basic-pane.
Generic Function, cg package
Arguments: system
This function has been replaced with default-gray-pixmap-color-vector and the new function should be used in place of this one. The new function does not take any arguments. This function takes one argument, but the one argument is in fact ignored. This function is kept for backward compatibility only. See default-gray-pixmap-color-vector for information on what this deprecated function does.
Generic Function, cg package
Arguments:
Returns the default-gray-pixmap-color-vector. This can be used to make an image that normally uses default-pixmap-color-vector appear "unavailable" by swapping this color vector into the texture-info that is used for the image and redrawing the image as usual with copy-to-stream or copy-pixels-to-stream.
default-gray-pixmap-color-vector is a property of the system class.
In releases prior to 7.0, this function was named default-gray-palette-vector and took one argument, which was in fact ignored. New code should use this function called without arguments.
Generic Function, cg package
Arguments: value-one value-two
This function is called by sort-grid if the on-sort-predicate function of the sort-column of the grid-widget is not a function name or function object.
As the examples below show, returns true is value-one is smaller (numerically or as strings) than value-two.
Whenever both of the values are numbers, it sorts the values numerically. Otherwise it sorts all values alphanumerically, where a string is compared directly and a symbol uses its symbol-name, but other values will cons a string on each call with prin1-to-string. So sorting may cause substantial consing unless either every value is a number or every value is either a string or a symbol.
Examples:
cg-user(44): (default-grid-sorter 1 2)
t
cg-user(45): (default-grid-sorter 2 1)
nil
cg-user(46): (default-grid-sorter "hello" "goodbye")
nilGeneric Function, cg package
Arguments: header-control
Returns the default header justification as passed by the :header-justification initarg to (make-instance 'header-control). The values can be :left, :right, or :center.
default-header-justification is a property of the header-control class.
Generic Function, cg package
Arguments: header-control
Returns the default header width as passed by the :header-width to (make-instance 'header-control).
default-header-width is a property of the header-control class.
Generic Function, cg package
Arguments: window-or-configuration
Returns the height to be used for a newly created window if an explicit height was not specified in the call to make-window. This function is called automatically by the system and should not be called by applications, but an application may supply default-height methods to specify the default sizes for its window subclasses.
default-height is called after the Lisp object for the window has been created but before the actual window has been created by the operating system. It returns an integer denoting the height to use for the new window.
The default version of these methods (for simple-streams) work as follows. The height is determined by:
If a method is supplied for the class of the window argument, and that method returns an integer (rather than nil), that value is used for the height. Otherwise:
If the value of (default-height (configuration \*system\*)) is true, use that value for the height. (It is nil initially though.)
If (default-height (configuration \*system*\)) is nil, multiply the height of the screen, (height (screen \*system\*)), by (default-height-factor (configuration *system*)) and use the result as the height.
default-height methods may be added for window subclasses of an application in lieu of passing the equivalent initargs for each window instance.
You can pass the :exterior-top-left argument to make-window in order to specify a particular position for the top-left corner of a window without overriding these default size methods. The top-left position will otherwise default to being offset somewhat from the position at which the previous window was created.
default-height is a property of the configuration class. See also default-width and default-top-left.
Generic Function, cg package
Arguments: configuration
Returns the default ratio of new window height to screen interior. This value is used to calculate the height of a new window when the arguments to make-window do not determine the height.
default-height-factor is a property of the configuration class.
Function, cg package
Arguments:
default-init-function is the default ide:on-initialization function for a project. It creates and displays the running window for the main form of the project, and then returns that window so that the application will exit when the main window is closed.
Below is the complete code for this function, which an application may model after if it needs to use a custom ide:on-initialization function.
(defun default-init-function ()
(let* ((maker (main-window-maker (app *system*)))
window)
;; This default project on-initialization function expects
;; the project to have a main form to run. For a project
;; that uses no windows at all, you would need to substitute
;; a different on-initialization function.
(unless maker
(error "The project has no main form to run. Either add a form ~
to the project or give the project a different ~
on-initialization function."))
;; Call the main form module's maker-function to create its window.
(setq window (funcall maker
;; When in a Run Project in the IDE,
;; run the main form on the screen (rather
;; than on the IDE owner window where
;; individual forms are run) to more completely
;; emulate the standalone application.
;; (The preferred initarg is now :owner, but
;; :parent also works with maker-functions
;; that were generated in pre-6.0 versions.)
:parent (screen *system*)))
;; Cache the main window so that its finder function will
;; find it later.
(when window
(add-application-window window)
;; Select the window if needed so that the end user sees it.
;; A custom on-initialization function might want to customize
;; the window contents in some way before revealing it here.
(select-window window)
;; This call may be needed especially in Windows 2000 to
;; ensure that the app comes to the front.
(set-foreground-window window))
;; Return the main window of the application, to tell
;; do-default-restart to call event-loop for us, passing the
;; window so that event-loop exits when the window has been closed.
;; Alternately, we could call event-loop ourselves with a
;; custom exit-test, and return anything but a window when
;; it returns.
window))Generic Function, cg package
Arguments: system
This function is deprecated in favor of the global variable *default-inverted-texture-info*. This function may cease to be supported in a future release. In the current release, it simply returns the value of *default-inverted-texture-info*. The system should be the current system, which is the value of *system*.
Function, cg package
Arguments:
Returns the default pixmap to use for all of the items of an outline that do not have subitems. The image is a blank page.
Generic Function, cg package
Arguments: menu menu-item window-or-screen
The symbol default-menu-on-click is the default value of the on-click event-handling property of a menu.
The default default-menu-on-click method simply returns the value of the chosen menu-item. Therefore, when pop-up-menu is called on a menu that uses this default on-click handler, the value of the chosen menu item is simply returned from pop-up-menu, and the calling function must decide what to do with the value. (Alternate on-click handlers, such as the built-in function funcall-menu-item, can be used instead to process any chosen item in some standard way before pop-up-menu returns. In fact, this must be done for pull-down menus, since they do not return values to the application.)
When the menu is a shortcut-menu, the default on-click function is still default-menu-on-click, but a different method of this generic function is used. This method expects the menu-item's value to be one of the following things:
A symbol naming a function, or a function object. In this case, the function will be called, passing window-or-screen as the only argument. (When the shortcut-menu is invoked by pop-up-shortcut-menu, as usual, window-or-screen will be the window that was passed to pop-up-shortcut-menu).
A window. In this case, the window is selected by calling select-window.
menu is the menu that contains the chosen menu-item.
menu-item is the menu-item that was chosen.
window-or-screen is either the window on which the menu was invoked with pop-up-menu, or else the window on which the menu was defined.
Function, cg package
Arguments:
Returns the default pixmap to use for all of the items of an outline whose subitems are currently being shown. The image is an open file folder.
Generic Function, cg package
Arguments: window interior-height scrollbarp
Returns a default page-height to use for window when no page-height has been explicitly specified with either a setf of the page-height function or the :page-height initarg. interior-height is the interior height of the window. scrollbarp is true if the vertical scrollbar was enabled for the window when it was created. The returned value is always in stream units (see cg-coordinates.html).
The default method returns the interior-height if the scrollbar is not enabled, and otherwise returns the height of the screen. An application may add default-page-height methods to define default page-heights for its own window classes. The method should always return a height and never return nil.
See also page-height and explicit-page-height (and also page-width, default-page-width, and explicit-page-width.)
Generic Function, cg package
Arguments: window interior-width scrollbarp
Returns a default page-width to use for window when no page-width has been explicitly specified with either a setf of the page-width function or the :page-width initarg. interior-width is the interior width of the window. scrollbarp is true if the horizontal scrollbar was enabled for the window when it was created. The returned value is always in stream units (see cg-coordinates.html).
The default method returns the interior-width if the scrollbar is not enabled, and otherwise returns the width of the screen. An application may add default-page-width methods to define default page-widths for its own window classes. The method should always return a width and never return nil.
See also page-width and explicit-page-width (and also page-height, default-page-height, and explicit-page-height.)
Generic Function, cg package
Arguments: system
This function has been replaced with default-pixmap-color-vector and the new function should be used in place of this one. The new function does not take any arguments. This function takes one argument, but the one argument is in fact ignored. This function is kept for backward compatibility only. See default-pixmap-color-vector for information on what this deprecated function does.
Generic Function, cg package
Arguments: frame-with-single-child
Returns the name of the class to instantiate for the single child pane of a frame-with-single-child class (thus, the default method for the bitmap-window class returns the symbol bitmap-pane). If you subclass frame-with-single-child, you should provide a default-pane-class method for your new class.
Generic Function, cg package
Arguments:
Returns the default-pixmap-color-vector. This is a color vector shared by the texture-infos of many Allegro pixmaps for efficiency. It contains the following sixteen colors:
An application pixmap that uses these 16 colors in this order could use this color vector in the colors slot of the texture-info used with the pixmap in order to reduce the total number of color vectors needed by the application. Pixmap-creating programs such as the Paint applet may create pixmaps that use this color order or a similar one that could be edited to this one.
An additional advantage of using default-pixmap-color-vector is that Allegro automatically changes the vector's gray entry to the system-edge-shadow-color, the light-gray entry to the system-dialog-background-color, and the white entry to the system-background-color. This means that button pixmaps using this color vector will automatically appear in the custom colors that the end user has set up in the Windows Control Panel.
default-pixmap-color-vector is a property of the system class.
Generic Function, cg package
Arguments: grid-widget
Returns the border color used by sections of grid-widget that do not have a border color specified.
default-section-border-color is a property of the grid-widget class.
Generic Function, cg package
Arguments: grid-widget
Returns the border width used by sections of grid-widget that do not have a border width specified.
default-section-border-width is a property of the grid-widget class.
Generic Function, cg package
Arguments: configuration
Returns the configuration's default pixel-height for tabs on a tab-control. The value nil means defer to the OS default. The current configuration, which provides the default currently in force, is (configuration *system*) (see configuration and *system*).
See the description of the tab-control class/control. default-tab-height is a property of the configuration class.
Generic Function, cg package
Arguments: configuration
Returns the configuration's default pixel-width for tabs on a tab-control. The value nil means defer to the OS default. The current configuration, which provides the default currently in force, is (configuration *system*) (see configuration and *system*).
See the description of the tab-control class/control. default-tab-width is a property of the configuration class.
Generic Function, cg package
Arguments: system
This function is deprecated in favor of the global variable *default-texture-info*. This function may cease to be supported in a future release. In the current release, it simply returns the value of *default-texture-info*. The system should be the current system, which is the value of *system*.
Generic Function, cg package
Arguments: window window-width window-height
This generic function is called when a window is created if none of the initargs to make-window (specifically :left and :top, :exterior-top-left, :exterior, or :interior) specifies a position for the window. Returns a default position at which to place the exterior upper-left corner of the new window. An application may add default-top-left methods to specify the default positioning for various window classes.
If the offset-from-selected-window configuration property is turned on (as it is by default), then the default default-top-left method will position the window just down and right (by the height of a titlebar) from the selected child window of the new window's parent window if any. Otherwise it places the window at the most recently used default position, which is initially the upper left of the screen.
A special wrapper method in the IDE defaults any windows that are owned by the invisible IDE owner window (the development-main-window) to a special location selected by the IDE, which is the position where new forms are placed. (When running the IDE, a window will in fact be owned by the IDE owner window if no :parent initarg is passed to make-window; in a standalone application a new window will be an ordinary top-level window by default.)
This generic function is similar to default-width and default-height, but differs in that those are also configuration properties while default-top-left is not a configuration property.
Generic Function, cg package
Arguments: window-or-configuration
Returns the width to be used for a newly created window if an explicit width was not specified in the call to make-window. This function is called automatically by the system and should not be called by applications, but an application may supply default-width methods to specify the default sizes for its window subclasses.
The default-width is used as described below when a window is created with make-window but neither the :exterior nor :interior arguments are specified.
The default-width is called after the Lisp object for the window has been created but before the actual window has been created by the operating system. It returns an integer denoting the width to use for the new window. The default version of this method (for simple-streams) works as follows. The width is determined by:
If a method is supplied for the class of the window argument, and that method returns an integer (rather than nil), that value is used for the width. Otherwise:
If the value of (default-width (configuration *system*)) is true, use that value for the width. (It is nil initially though.)
If (default-width (configuration *system*)) is nil, multiply the width of the screen, (width (screen *system*)), by (default-width-factor (configuration *system*)) and use the result as the width.
default-width methods may be added for window subclasses of an application in lieu of passing the equivalent initargs for each window instance.
You can pass the :exterior-top-left argument to make-window in order to specify a particular position for the top-left corner of a window without overriding these default size methods. The top-left position will otherwise default to being offset somewhat from the position at which the previous window was created.
default-width is a property of the configuration class. See also default-height and default-top-left.
Generic Function, cg package
Arguments: configuration
Returns the default ratio of new window width to screen interior. This value is used to calculate the width of a new window when the arguments to make-window do not determine the width.
default-width-factor is a property of the configuration class.
Macro, cg package
Arguments: class-name superclass-names slot-specifiers &rest class-options
Defines a class that has properties, so as to effectively combine a defclass expression with an associated defproperties expression. defcomponent is similar to defclass, except that a :properties option may be specified as follows:
(defcomponent thing
((color ...)
(size ...))
(:default-initargs
:color red
:size 4)
(:documentation "A silly class")
(:properties
(color
:help-string "Color of the thing."
:type rgb-or-nil
:editor-type :color)
(size
:help-string "How big the thing is."
:type positive-integer)
))More examples are on the defproperties page.
The format of the properties option is similar to defproperties except that the symbol define-property is not needed at the beginning of the list for each property.
A property may define any of the following property facets, listed here with the initarg that is used to specify each:
:reader: the name of a function for reading the property value. Defaults to the property name. (Always naming the property the same as the reader function is recommended.)
:writer: the name of a function for writing the property value. Defaults to the setf of the property name. (Using the setf of the reader function for the writer is recommended.) If a separate writer function is provided, it should be written to perform any side effects that are needed to keep the object and its environment in a consistent state.
Note on :reader and :writer: The name of the reader and writer functions for a property default to the name of the property and the setf of the name of the property respectively. But defining a property does not actually create the reader and writer functions for the property (regardless of whether the reader and writer names are specified explicitly), so the application must define these functions separately. Typically, a property is defined for a class and has the same name as a slot of the class, and the accessor methods that are created for the slot serve as the reader and writer of the property as well. Otherwise the reader and writer functions must be defined explicitly. See below for examples.
:type: a Lisp type that the property value must satisfy. The inspector will prevent invalid values from being used. Defaults to t, to allow any value.
:dependent-properties: a list of the names of other properties of the object whose values might be changed by the writer function as side effects. The Inspector uses this to redisplay related properties whenever the user changes a property value in the inspector. (In general, the Inspector does not know automatically to redisplay values that have changed once it has inspected an object, and the Refresh Values command on the Inspector's right-button shortcut menu may be used to ensure that the displayed values are current.)
:initarg: a keyword used by recreation-code to generate a Lisp expression for recreating an object that has this property. Defaults to the keyword that has the same name as the property name symbol.
:help-string: a short documentation string for the property, or nil. Defaults to nil.
:editor-type: a value specifying which kind of extended editing will be used by the inspector for the property when the user clicks on the small button to the right of the value. Options are:
:long-expression: pops up a multi-line text editor. This is the default.
:multiple-choice: drops a list of choices.
:toggle: toggles between the choices when clicked. The default choices for :toggle are t and nil.
:color: pops up the color-selection dialog.
:font: pops up the font selection dialog.
:path: pops up the file selection dialog.
:menu: pops up the menu editor dialog.
:function: finds source code or generates skeleton code.
:choices: a list of possible values for use by the inspector when the editor-type is :multiple-choice or :toggle. Defaults to nil, unless the editor-type is :toggle, in which case the default is a list of t and nil.
:read-only: a flag to prevent modification of the property in the inspector. Defaults to nil.
:remake: a flag to indicate that the object that has this property should be recreated when this property is modified in order to completely effect the change. Defaults to nil.
:hidden: a flag to indicate that the inspector should not show this property. Useful when a property is inherited but is not useful on a particular subclass. Defaults to nil.
:repositioning (for controls): a flag to indicate that the control may be moved or resized when this property value is modified. Used internally to update handles on forms when needed. Defaults to nil.
Properties of CLOS classes inherit similarly to slots. Only those facets that differ from the inherited property need be specified for a given class, and properties that have no differing facets need not be specified at all.
Properties are shown on a separate tab of the inspector, and thus can serve as a relatively high-level interface to the object by providing a selected subset of the object's internal attributes, where each property knows to either disallow modification or to cause appropriate side effects upon modification in order to maintain a consistent environment.
Macro, cg package
Arguments: name &rest args &key reader writer accessor type dependent-properties initarg help-string remake editor-type read-only choices hidden repositioning
Defines an individual property within a defproperties form. On the defproperties page, there is an example which contains examples of calls to define-property.
This macro defines a property but does not associate it with any class or object. A property is an attribute of an object that defines a high-level means of accessing the attribute value. Properties are largely used by the inspector for editing objects that have properties, though they are useful programmatically as well mostly because a property defines how to cause any appropriate side effects when the property value is modified. A property for a CLOS object is typically based on a slot of the object, but properties are generally independent of any internal representation and can be defined for any Lisp type.
A property may define any of the following property facets, listed here with the initarg that is used to specify each:
:reader: the name of a function for reading the property value. Defaults to the property name. (Always naming the property the same as the reader function is recommended.)
:writer: the name of a function for writing the property value. Defaults to the setf of the property name. (Using the setf of the reader function for the writer is recommended.) If a separate writer function is provided, it should be written to perform any side effects that are needed to keep the object and its environment in a consistent state.
Note on :reader and :writer: the name of the reader and writer functions for a property default to the name of the property and the setf of the name of the property respectively. But defining a property does not actually create the reader and writer functions for the property (regardless of whether the reader and writer names are specified explicitly), so the application must define these functions separately. Typically, a property is defined for a class and has the same name as a slot of the class, and the accessor methods that are created for the slot serve as the reader and writer of the property as well. Otherwise the reader and writer functions must be defined explicitly. See the examples at the end of the defproperties entry.
:accessor: use instead of :read and :writer. Provides a reader and a setf method for the reader which works as a writer. Using the same name as the property is recommended. :type A Lisp type that the property value must satisfy. The inspector will prevent invalid values from being used. Defaults to t, to allow any value. :dependent-properties A list of the names of other properties of the object whose values might be changed by the writer function as side effects. The Inspector uses this to redisplay related properties whenever the user changes a property value in the inspector. (In general, the Inspector does not know automatically to redisplay values that have changed once it has inspected an object, and the Refresh Values command on the Inspector's right-button shortcut menu may be used to ensure that the displayed values are current.)
:type: a type-specifier indicating the type of values that are allowed for this property. Any type-specifier may be used, such as the symbol integer or the list (and integer (satisfies evenp)), just as with the type-specifier argument to typep. This type is used only by the IDE inspector, which will reject a value that a user interactively enters for a property if the value is not of that type.
:dependent-properties: a list of the names of other properties whose values may change as a direct result of changing the value of this property. This list is used only by the IDE inspector, which will immediately update its display of any of these dependent properties that exist for an inspected object whenever the user interactively changes the value of this property.
:initarg: a keyword used by recreation-code to generate a Lisp expression for recreating an object that has this property. Defaults to the keyword that has the same name as the property name symbol.
:help-string: a short documentation string for the property, or nil. Defaults to nil.
:editor-type: specifies which kind of extended editing will be used by the inspector for the property when the user clicks on the small button to the right of the value. The options are:
:long-expression: Pops up a multi-line text editor. This is the default.
:multiple-choice: Drops a list of choices.
:toggle: toggles between the choices when clicked. The default choices for :toggle are t and nil.
:color: Pops up the color-selection dialog.
:font: Pops up the font selection dialog.
:path: Pops up the file selection dialog.
:menu: Pops up the menu editor dialog.
:function: Finds source code or generates skeleton code.
:choices: a list of possible values for use by the inspector when the editor-type is :multiple-choice or :toggle. Defaults to nil, unless the editor-type is :toggle, in which case the default is a list of t and nil.
:read-only: a flag to prevent modification of the property in the inspector. Defaults to nil.
:remake: a flag to indicate that the object that has this property should be recreated when this property is modified in order to completely effect the change. Defaults to nil.
:hidden: a flag to indicate that the inspector should not show this property. Useful when a property is inherited but is not useful on a particular subclass. Defaults to nil.
:repositioning (for controls): a flag to indicate that the control may be moved or resized when this property value is modified. Used internally to update handles on forms when needed. Defaults to nil.
Properties of CLOS classes inherit similarly to slots. Only those facets that differ from the inherited property need be specified for a given class, and properties that have no differing facets need not be specified at all.
Properties are shown on a separate tab of the inspector, and thus can serve as a relatively high-level interface to the object by providing a selected subset of the object's internal attributes, where each property knows to either disallow modification or to cause appropriate side effects upon modification in order to maintain a consistant environment.
Macro, cg package
Arguments: class-name &rest properties
Defines a set of properties for a class. A property is an attribute of an object that defines a high-level means of accessing the attribute value. Properties are largely used by the inspector for editing objects that have properties, though they are useful programmatically as well mostly because a property defines how to cause any appropriate side effects when the property value is modified. A property for a CLOS object is typically based on a slot of the object, but properties are generally independent of any internal representation and can be defined for any Lisp type. Properties are defined with define-property. The various property initargs are described on that page.
As an example, below is a part of the defproperties expression for the existing control class header-control. Here the properties are defined with define-property. (To make a defproperties form less verbose, each occurrence of the symbol define-property within the form may be excluded if desired, as shown is the second form.)
(defproperties header-control
(define-property available
:type boolean
:editor-type :toggle)
(define-property header-width
:type positive-integer
:reader default-header-width
:writer (setf default-header-width)
:editor-type :short-expression)
(define-property header-justification
:type justification
:editor-type :multiple-choice
:reader default-header-justification
:writer (setf default-header-justification)
:choices :justification-values)
(define-property button-style
:type boolean
:editor-type :toggle
:remake t)
(define-property on-range-change
:type event-handler
:editor-type :function)
(define-property on-set-focus
:type event-handler
:editor-type :function)
)
;; Here is the shorter form with define-property left out:
(defproperties header-control
(available
:type boolean
:editor-type :toggle)
(header-width
:type positive-integer
:reader default-header-width
:writer (setf default-header-width)
:editor-type :short-expression)
(header-justification
:type justification
:editor-type :multiple-choice
:reader default-header-justification
:writer (setf default-header-justification)
:choices :justification-values)
(button-style
:type boolean
:editor-type :toggle
:remake t)
(on-range-change
:type event-handler
:editor-type :function)
(on-set-focus
:type event-handler
:editor-type :function)
)Reader and writer examples. This includes examples of calls to defcomponent.
;; This example shows the typical case of defining properties
;; for a standard-class, where the accessor methods that
;; are automatically created for the size slot are also
;; used by default as the reader and writer of the associated
;; size property. This technique of sharing
;; the name is recommended wherever it is feasible.
(defcomponent foo ()
((size :initarg :size
:initform nil
:accessor size))
(:default-initargs
:size :big)
(:properties
(size
:help-string "How big it is."
:type (member :big :medium :little nil)
:editor-type :multiple-choice
:choices '(:big :medium :little))))
(setq f (make-instance 'foo :size :little))
(inspect f)
;; ------------------------------------------------------
;; This example defines a property that computes its
;; value each time it is read rather than reading a
;; cached value from a slot.
(defcomponent yellow-item-list (single-item-list)
()
(:default-initargs
:background-color yellow)
(:properties
(how-many
:read-only t)))
(defmethod how-many ((control yellow-item-list))
(length (range control)))
(setq c (make-instance 'yellow-item-list
:range '(a b c d)))
(inspect c)
;; -----------------------------------------------------------
;; This example does the same thing for an existing class, using
;; defproperties instead of defcomponent
(defproperties single-item-list
(define-property how-many
:read-only t))
(defmethod how-many ((control single-item-list))
(length (range control)))
(setq d (make-instance 'single-item-list
:range '(a b c d e)))
(inspect d)
;; -----------------------------------------------------------
;; This example demonstrates defining a property
;; on a non-standard class, using an arbitrary place
;; to hold the property values (since there is
;; no slot for the property).
(defproperties integer
(define-property roundness))
(defparameter *integer-roundness* (make-hash-table))
(defmethod roundness ((integer integer))
(gethash integer *integer-roundness* :unknown))
(defmethod (setf roundness)(value (integer integer))
(setf (gethash integer *integer-roundness*) value))
(setf (roundness 6) :quite)
(inspect 5)
(inspect 6)If the inspector should treat some instances of a class differently than other instances, that can be achieved by adding methods to one or more of the following generic functions: property-reader, property-writer, property-type, property-editor-type, property-choices, property-help-string, property-remake, property-read-only, and property-hidden.
Generic Function, cg package
Arguments: cg-configuration
When the value of this configuration option is true, then if pop-up-menu is called while any mouse button is down, the menu will not appear until all mouse buttons have been released. The pop-up menu code does this by simply calling wait-for-mouse-buttons-up before showing the menu. When nil, there is no delay.
The default value is nil.
This option does not appear on the IDE's Options dialog, but could be set to nil programmatically with the following form:
(setf (delay-pop-up-menus-until-mouse-buttons-up
(configuration *system*))
nil)Generic Function, cg package
Arguments: object
Disables all drawing on object until a resume-redraw is subsequently called on the object. object may be a window or a dialog-item (control). Refer to with-delayed-redraw for more information.
Generic Function, cg package
Arguments: grid-widget
Returns whether grid-widget (which must be a grid-widget) will delay writing interactive user edits back to application data areas, to allow the user to either confirm or reject the changes sometime later. The value may be set by passing the delay-write-cell-value initarg at creation time, or any time later by calling (setf delay-write-cell-value). The default value is nil.
If nil, then any interactive edit to the value displayed in a grid cell will immediately call an application write-cell-value method or data-writer function to store the new value into an application data area.
If true, then a write-cell-value:around method will hold the new value internally until the application either calls write-delayed-cell-values to write all pending changes, or calls clear-delayed-cell-values to cancel all pending changes and redisplay the previous values.
Obscure note: if you (atypically) set this property to nil for an existing grid-widget that may be holding delayed values at the time, then you should probably call either write-delayed-cell-values or clear-delayed-cell-values just before that.
Generic Function, cg package
Arguments: standard-object
Returns the value of the delayed property of standard-object.
For a scroll-type control such as a horizontal-scroll-bar or a trackbar, the delayed property determines whether on-change is called to update the control's value continuously as the user drags the scroll-box or pointer along the slider, or whether it is called only once at the end of the scroll gesture.
For text controls such as an editable-text or combo-box, the delayed property determines whether on-change is called to update the control's value as each character is typed, or whether it is called only once after the user has finished typing and moves the keyboard focus from the control. If you use the the delayed property on one of those controls but you need the latest value of the control, you may have to use fetch-control-value rather than value. Examples are given in the description of fetch-control-value.
For the split-bar control, the delayed property determines whether side effects occur continuously during a drag, or only once at the end of a drag.
Here are the widgets, along with the values and the associated behaviors.
value nil: Editable text is updated immediately after each keystroke.
value t: Editable text is updated when the keyboard focus moves from the control.
value nil: Editable text is updated immediately after each keystroke.
value t: Editable text is updated when the keyboard focus moves from the control.
up-down-control: when nil, the on-change functions of both the up-down-control and its buddy editable-text widget (if any) will be called each time the value increments as the user holds the mouse button down after clicking on the up-down-control.
When t: the on-change functions of both the up-down-control and its buddy editable-text widget (if any) will be called a single time when the mouse button is released, though the incrementing values will still be displayed in the buddy widget as the user holds the mouse button down.
value nil: Side effects are performed continously as the user drags the split-bar to a new location. (That is, once each time the system notices that the split-bar has moved by one or more pixels.) Side effects include moving and resizing any widgets in the widgets-to-move and widgets-to-resize properties, as well as calling the split-bar's on-change function if any.
value true: Side effects are performed only once at the end of drag.
delayed is a property of the following classes:
combo-box, editable-text, horizontal-scroll-bar, multi-line-editable-text, trackbar, up-down-control, vertical-scroll-bar.
Generic Function, cg package
Arguments: grid-subsection
Returns whether the user may interactively delete the grid row or column. When the user presses the DELETE key, a list of all rows and columns that are marked as deletable and which are selected (typically by clicking the header cell) is passed to the function delete-selected-subsections. Before deletion actually occurs, confirm-grid-subsection-deletion is called (by the system) to confirm the user's intention.
deletable is a property of the grid-subsection, grid-column, row-header-column, grid-row, and column-header-row classes.
Function, cg package
Arguments: class-grid data-object
Removes one of the displayed objects from a class-grid. An alternative is to replace the whole set of displayed objects by calling (setf value) on the grid, passing a list of all objects to display.
Internally this removes a class-grid-body-row from the body row-section of the class-grid.
class-grid is the class-grid from which an object will be removed.
data-object is the object to remove. It should be an instance of the edited-class of the class-grid. If the object is not found in the class-grid, then nothing is done.
See also add-class-grid-row.
Generic Function, cg package
Arguments: column
Deletes a grid-column (of a grid-widget) from its grid-column-section, removing it from the section's subsections list, and moving and/or stretching other columns in the section (depending on the proportional property of the objects) to fill the space that had been occupied by the deleted column.
See also delete-row and delete-selected-subsections.
Generic Function, cg package
Arguments: window-or-widget
Deletes an object from the specified window or widget if possible. Does not place anything onto the clipboard as copy-command and cut-command do.
window-or-widget should an instance of the basic-pane, dialog-item, or screen class or one of their subclasses.
This function behaves as copy-command does to pass its action to a child window, except that it calls delete-selection rather than copy-selection on the child window. See copy-command for more information.
Here is the default method for windows and the screen:
(defmethod delete-command ((stream screen-stream))
(let* ((child (selected-window stream)))
(if* child
then (delete-command child)
else (delete-selection stream))))In earlier releases, use of this operator was deprecated. It has now been restored to approved status.
Generic Function, cg package
Arguments: row
Deletes a grid-row (of a grid-widget) from its grid-row-section, removing it from the section's subsections list, and moving and/or stretching other rows in the section (depending on the proportional property of the objects) to fill the space that had been occupied by the deleted row.
See also delete-column and delete-selected-subsections.
Generic Function, cg package
Arguments: grid-widget &key (confirm t)
Conditionally deletes the grid-rows and grid-columns of grid-widget (which must be an instance of grid-widget) that are both deletable and selected. If confirm is true (the default), then confirm-grid-subsection-deletion is called, and the deletion is done only if that overridable generic function returns true. If confirm is nil, then the deletion is always done. The return value is the list of subsections that were deleted; this is nil if no subsections were selected or if the user canceled the confirmation dialog.
There is a delete-selection method for grid-widgets that calls delete-selected-subsections, so an application could call either. In the IDE, the Edit | Delete command calls delete-selection, so its keyboard shortcut (the Delete key) will call this function automatically. A standalone application would need to call this function in its own way instead.
Alternately, delete-row and/or delete-column can be called to delete individual rows and columns regardless of their state, and (setf subsections) can be called to replace the whole set of rows or columns. delete-selected-subsections calls delete-row or delete-column to delete each subsection, so an application's wrapper methods on those generic functions would catch deletions that are done in either way.
Generic Function, cg package
Arguments: window-or-widget
Deletes the selected object (if any) in window-or-widget, if it knows how to do so for the particular window or widget. Returns true if a deletion was done, and nil otherwise.
window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass.
The default method always does nothing (and therefore returns nil). Otherwise the methods behave the same cut-selection.
See cg-clipboard.html.
Generic Function, cg package
Arguments: grid-widget &optional excepted-subsection invalidate-borders-p
Deselects all grid rows and columns of a grid-widget that are currently selected (see selected).
grid-widget is a grid-widget control.
excepted-subsection may be either nil or a grid-row or grid-column which is not to be deselected. This allows leaving a single row or column selected.
If invalidate-borders-p is true, then both the interiors and the borders of the deselected subsections will be redrawn, rather than the interiors only.
Generic Function, cg package
Arguments: grid-widget
Returns what happens to selected grid rows and columns of grid-widget when the keyboard focus moves away from the grid.
The value can be t or nil. If nil, any selected subsections in the grid are still selected after the focus moves away from the grid-widget.
If the value is t, all grid subsections are deselected when the focus moves off the grid-widget.
deselect-sections-when-lose-focus is a property of the grid-widget class.
Generic Function, cg package
Arguments: grid-widget
Returns what happens to selected grid rows and columns of grid-widget when the keyboard focus moves to another subsection of the grid.
The value can be t or nil. If nil, any selected subsections in the grid are still selected after the focus moves to another cell.
If the value is t, deselects all grid subsections when the focus moves to another cell within the grid.
deselect-sections-when-move-focus is a property of the grid-widget class.
Generic Function, cg package
Arguments: grid-widget section subsection &optional invalidate-borders-p
Use of the function is deprecated. Use (setf selected) instead.
Deselects a grid row or column if it is currently selected (see select-subsection), and otherwise does nothing.
grid-widget is a grid-widget control.
section is either a column-section or a row-section.
subsection is either a grid-row or a grid-column.
If invalidate-borders-p is true, then both the interior and the border of the subsection will be redrawn, rather than the interior only.
See also deselect-all-subsections.
Function, cg package
Arguments: handle
This function is specific to the Windows platform, and will have no effect elsewhere. On other platforms, pixmaps can be used where icons are used on Windows.
Destroys the icon indicated by the handle argument so that the icon can no longer be drawn, freeing the associated operating system resources. It is not normally necessary to call this function, since icon resources are always freed when Lisp is exited. But if an application creates many icons, then it is possible to run out of icon resources, in which case this function should be called on icons that are no longer being used.
It is safe to call this function on an icon if all of the following are true:
The icon is no longer the icon property of any window.
The icon is no longer the pixmap-icon property of any pixmap that may still get drawn.
The application will no longer draw the icon explicitly by calling draw-icon.
handle should be an integer that was returned by a call to either extract-icon-from-file or create-icon-handle.
Generic Function, cg package
Arguments: pixmap-handle
Destroys the "device-dependent pixmap" indicated by the handle argument, freeing the associated operating system resources.
This function is largely for the backward compatible style of using separate objects for the texture, mask, texture-info, and pixmap handle of a pixmap. It is now recommended instead to use a pixmap object, which encapsulates all of these. With a pixmap object, call close-pixmap-handle (rather than this function) to cause the pixmap to stop using a handle to a device-dependent pixmap and to free up the OS resources it uses.
It is safe to call this function if the application will no longer be passing this pixmap handle (or a pixmap object that still uses it) to copy-to-stream or copy-pixels-to-stream.
Generic Function, cg package
Arguments: system
Returns the development-main-window of system. The current system is the value of *system*.
When the IDE is present, this function returns the main IDE window that is the owner of the various IDE tool windows. See ide:main-ide-window and ide:use-ide-parent-window. When the IDE is not present (either in a standalone Common Graphics application or in a development Lisp that has loaded Common Graphics but not the IDE), this function returns the screen.
The owner argument to the function make-window defaults to the value returned by development-main-window. This means that the default owner of a window created in the IDE will be the ide:main-ide-window, so that the window will exist "within the IDE" for convenience. Otherwise the default owner of a window is the screen.
development-main-window is a property of the system class.
Generic Function, cg package
Arguments: form
Returns class of a window or the class to instantiate when running a form (that is, it is the accessor/setter of the class slot of a form). A form (a special window used to design actual application windows) is always an instance of the form class, to provide its special widget-editing behavior. The class property indicates the intended class that should be instantiated for the application when the form is run or the window associated with the form is created. This function accesses the class slot (since class is a Common Lisp symbol, its name is not available to be the accessor/setter).
But note that it is uncommon to need to use that function programmatically (one typically sets the class slot upon creation of a window with make-window or using the class slot in an inspector window). The form (using Common Lisp functions) (class-name (class-of object)) also serves as an accessor.
This function can also be applied to a window object which is not a form, in which case it returns what (class-name (class-of object)) would return, the class of the window.
Macro, cg package
This function is no longer supported.
Generic Function, cg package
Arguments: window
Returns an integer that identifies the device-context of window if it has one, or nil otherwise. A device-context is a construct used in the Windows API to specify a set of parameters that are used when drawing on a window. A common graphics application does not normally need to deal with a window's device-context directly, but if you need to pass the window to a winapi function that calls for the window's device-context (or hDC), then you should pass the integer returned by this function for that argument. See also windows:handle, which returns the window's "handle".
Every non-control window in common graphics (and every lisp-widget window) is automatically assigned a device-context, which it keeps until it is closed. Controls supplied by the OS (all controls except lisp-widgets), on the other hand, are not automatically given device-contexts in Lisp since it is normally only the OS rather than Lisp that draws on the control. If you do want to draw directly on a non-Lisp control, then you must give the window of the control a device-context while drawing on it. The easy way to do this is to wrap a call to with-device-context around the code that draws on the control.
Generic Function, cg package
Arguments: stream position-or-box
Modifies position-or-box to convert its coordinates from pixel units to "dialog units". The Windows operating system defines a dialog unit as being one-fourth a system font character width horizontally and one-eighth of a system font character height vertically. We discourage the use of dialog units since it can vary from one machine to another depending on the size of the system font implemented by each video device driver.
The stream argument is ignored.
In releases prior to 6.0, this function was named screen-to-dialog-units. The old name can be used for backward compatibility.
Generic Function, cg package
Arguments: stream position-or-box
Argument stream should be a cg-stream. For a stream that has the scaling-stream mixin, converts a position or box from pixel units to scaled units (destructively modifying it). For other streams, simply returns the position or box that was passed.
Generic Function, cg package
Arguments: stream position-or-box
Converts a position or box that is in device units (directly relative to the physical interior upper left corner of the device (typically a window) specified by stream) so that it is in stream units (offset from its position relative to the physical interior upper left corner of window according to the scroll position and origin of stream).
Destructively modifies the position-or-box argument.
In earlier releases, this function was named window-to-stream-units. The old name can be used for backward compatibility.
Function, cg package
Arguments: dialog name
Returns the value of a control on a dialog. The dialog argument can be either a dialog object or the name of a dialog. The name argument is the name of the control (on that dialog) whose value is to be returned.
See also dialog-fields.
Macro, cg package
Arguments: dialog &rest names
Returns multiple values indicating the value of each of a set of widgets on a dialog. The dialog argument can be either a dialog object or the name of a dialog. Each successive argument is the name of a widget (a member of the dialog-item class) on that dialog, whose value is to be returned as the next returned value.
See also dialog-field.
Generic Function, cg package
Arguments: window
Returns the dialog-item (i.e. control) associated with window, or nil if window is not the window of a dialog-item. Dialog-items (i.e. controls) are displayed in a child-window of the parent dialog. This window is typically co-extensive with the control and so is not visible as a window to users. However, certain functions operate on the window and others operate on the control. This function and the function window return the control given the window and the window given the control, respectively.
Generic Function, cg package
Arguments: x
Returns true if its argument is a dialog-item (i.e. control suitable to be placed on a dialog) and returns nil otherwise.
Generic Function, cg package
Arguments: basic-pane
Returns a list of dialog-items (i.e. controls) on basic-pane. This list should not be modified although a new list can be set with setf.
Generic Function, cg package
Arguments: stream position-or-box
Returns position-or-box after modifying it so that the dimensions are in pixel (screen) units rather than dialog units.
In releases prior to 6.0, this function was named dialog-to-screen-units. The old name can be used for backward compatibility.
Generic Function, cg package
Arguments: stream position-or-box
The name of this function was changed in release 6.0 to dialog-to-device-units. See the description of that function for details. The symbol dialog-to-screen-units continues to name that function as well, for backward compatibility.
Generic Function, cg package
Arguments: dialog-item
Returns whether dialog-item's coordinates are specified in dialog-units rather than in pixels. If true, then the dialog-item's coordinates are measured in dialog-units, which are defined as one-fourth of a system-font space width wide or one-eighth of a system-font line-height high. If nil, the coordinates are in pixels, which are the coordinates that are usually used by common graphics.
Dialog-items will be created using pixel coordinates unless the :dialog-units-p initarg is passed as true when creating the dialog-item with make-instance.
Because the system-font varies from one machine to the next, using dialog-units is discouraged.
Generic Function, cg package
Arguments: x
Returns true if its argument is an instance of class dialog and returns nil otherwise.
Function, cg package
Arguments: character
Returns true if either digit-char-p returns true for the specified character or the character is a space.
character should be a character. Otherwise it is an error.
This function is handy as a predicate function in the *template-chars* association list, to allow the user to type either a numeral or a space at a certain position.
function, cg package
Arguments:
Returns a list of zero or more of the keyword symbols shown below, indicating the capabilities of the computer's touch input device, if it has one. nil will be returned if there is no touch input device.
Here are Microsoft's explanations of the capabilities. Apparently integrated means built into the computer (such as its screen) while external means connected to it (such as a tablet). Multiple inputs refers to multiple simultaneous fingers (or pens).
:integrated-touch - an integrated touch digitizer is used for input.
:external-touch - an external touch digitizer is used for input.
:integrated-pen - an integrated pen digitizer is used for input.
:external-pen - an external pen digitizer is used for input.
:multi-input - an input digitizer with support for multiple inputs is used for input.
:ready - the input digitizer is ready for input. If this value is unset, it may mean that the tablet service is stopped, the digitizer is not supported, or digitizer drivers have not been installed.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
function, cg package
Arguments:
Returns true if the computer has a touch input device that is currently enabled and working, and nil otherwise. This is the same as the :ready indicator returned by digitizer-capabilities.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: scroll-bar-mixin
Returns the value of the direction-of-increase property of the argument. The value of this property can be :up or :down. It indicates the direction a vertical scroll bar bubble or trackbar pointer moves when the value of the scroll-bar/trackbar increases. :up and :down are also used for horizontal scroll bars, with :up meaning to the left and :down meaning to the right.
direction-of-increase is a property of the trackbar, horizontal-scroll-bar, and vertical-scroll-bar classes.
Generic Function, cg package
Arguments: dialog-item
Returns whether Microsoft Visual Styles is disabled for a particular widget, identified by the dialog-item argument. (This widget property has no effect on non-Windows platforms.) The value may be set at creation time by passing the disable-visual-styles initarg, or any time later by calling (setf disable-visual-styles).
The value should be true to disable the usual Visual Styles effects for the widget, or nil to use Visual styles for it as usual. The default value is nil.
Visual Styles reflect the current theme that the user has chosen for their whole Windows environment. Sometimes this theme can override a property of a widget, such as its background-color. To stop that from happening, you can set the disable-visual-styles property of the widget to true, though this may result in a generally plainer style for that widget.
Function, cg package
Arguments:
Discards all events (except repaint messages) from the OS that are currently queued up, so that they are never handled. Repaint messages are handled rather than discarded.
Generic Function, cg package
Arguments: media-player
Returns whether the :display-controls initarg was passed as true to make-instance when creating an audio-player or video-player widget. Calling the setf of this function will have no effect; the value must be passed as an initarg at creation time.
Generic Function, cg package
Arguments: html-widget-or-browser uri-or-path
Displays a web page or an HTML or plain text file in an html-widget. Alternately you can set the value property of the html-widget.
html-widget-or-browser should be either an html-widget or an html-browser. When a browser is specified, it sets the value of the html-widget that's in the browser dialog.
uri-or-path should be either the URL of a web page (a string) or the pathname or path namestring of a file that contains HTML or plain text.
As a special case, a post can be done by passing the uri-or-path argument as a plist that contains the keys :uri and :post-string. The :uri value should be a URI as usual and the :post-string value should be the string to post, as in (:uri "http://foo.com" :post-string "The string to post.").
See the html-widget control.
Generic Function, cg package
Arguments: object-editor instance &key no-save-current
This is the general function for displaying an arbitrary object in an object-editor dialog. To instead display the first, last, next, or previous instance of the dialog's sorted list of instances, display-special-instance may be called instead.
object-editor is the object-editor that will display the object.
instance is the object to display. It should be an instance of the edited-class of the object-editor.
If no-save-current is nil, as it is by default, then object-editor-save will be automatically called to save any user modifications to the currently-displayed instance before displaying the new instance. If true, then this is not done, and so any edits to the current-instance are discarded.
Function, cg package
Arguments: pixmap &key surrounding-color title
Displays the specified pixmap in a new web browser tab. This function should only be called if js-mode indicates that CG is running in CG/JS mode. surrounding-color, if not nil, should be an RGB object (see make-rgb) for the background-color that will surround the pixmap in the new tab. title, if not nil, should be a string to display in the small rectangle above the tab interior (which the user clicks to select that tab).
The new browser tab is not a CG tab, so the user could right-click the image and select the browser's standard "Save Image to File" command to save the pixmap to a file on the client machine. (The CG function save-pixmap saves a file on the server machine.)
Generic Function, cg package
Arguments: object-editor type
Displays the first, last, next, or previous instance of an object-editor dialog's sorted list of edited-instances. To display some other instance, call display-instance instead.
The sorted list that determines which instance is displayed is an internally cached list and not the official list of instances in the edited-instances property, if any. See primary-name-slot.
Four of the built-in command-buttons may be used to call this function, or it can be called in some other way. An application could add wrapper methods to catch whenever an object-editor displays an instance.
object-editor is the object-editor that will display the instance.
type should be one of the keywords:
:first: display the first instance in the internal sorted list.
:last: display the last.
:next: display the instance that is just after the current-instance in the sorted list, if any, and otherwise will do nothing.
:previous: like :next for the previous instance.
Function, cg package
Arguments:
Returns true if the user is on a Mac, or nil otherwise.
In CG/JS mode (and thus always on the Mac and Linux), the returned value reflects the platform where the web browser is running, rather than where the CG Lisp application is running, which may be different when the CG app is running in server mode.
This function may be convenient when defining the event-synonym of a menu-item, when the keychords are different on the Mac (such as by employing the Command key, which is called meta-key in CG). Otherwise each such case would need to use the functions js-mode and web-browser-os along with #+macosx and #-macosx conditionalizations to determine the proper key to use in every case. This function does that for you. For example:
(make-instance 'menu-item
:value 'reload
:title "~Reload"
:event-synonym (cond ((displaying-on-mac) '(meta-key #\R))
(t '(control-key alt-key #\R))))Generic Function, cg package
Arguments: window-or-widget-or-nil &key (position (and window-or-widget-or-nil :center)) (mouse-button :left) (pre-expose t) (preview-seconds 0.5)(down-seconds 0.5)
This generic function is specific to Microsoft Windows, and should not be called on other platforms.
This generic function programmatically emulates clicking a mouse button, after optionally exposing a window and/or moving the mouse cursor over it. This may be useful for automated testing.
window-or-widget-or-nil may be either a window, a dialog-item, or nil. If this argument is non-nil and pre-expose is true, then the specified window or widget and all of its ancestor windows are selected so that the window or widget is in front to receive the mouse click. The position argument will also be relative to this window or widget.
The keyword arguments are:
position: may be a position, or the special keyword :center, or nil. If non-nil, then the mouse cursor is moved to the indicated position before the mouse click is done. If window-or-widget-or-nil is non-nil, then the position is in that object's stream coordinates, and otherwise it is a screen position. The special :center value indicates the center of that object's client area. The default value is :center if window-or-widget-or-nil is non-nil, and nil otherwise.
Note that the mouse cursor is left at the specified position. If you would like to return the mouse cursor to where it was previously, then you should first call cursor-position or ncursor-position and save the current position, then call do-click, and finally call (setf cursor-position) to return the mouse cursor to its original position.
mouse-button: may be either :left, :middle, or :right to indicate which mouse button is to be clicked. The default is :left.
pre-expose: if this argument is true and window-or-widget-or-nil is non-nil, then that window or widget and all its ancestor windows are selected before the click is done, so that it is in front to receive the click. The default is t.
preview-seconds may be either a non-negative number indicating the number of seconds to sleep before pressing the mouse button, or nil to not sleep at all. The default is 0.5.
down-seconds may be either a non-negative number indicating the number of seconds to sleep after pressing the mouse button down but before releasing it, or nil to not sleep at all. The default is 0.5.
;; Left-click at the center of a window's scrollable page.
(do-click some-window)
;; Left-click near the upper-right corner of its scrollable page.
(do-click some-window
:position (make-position (- (interior-width some-window) 8)
12))
;; Left-click it with no pause for people to watch the action.
(do-click some-window :preview-seconds nil :down-seconds nil)
;; Right-click in the center of a window's scrollable page.
(do-click some-window :button :right)
;; Left-click whatever is under the mouse.
(do-click nil)
;; Left-click an arbitary position on the screen.
(do-click nil :position (make-position 100 200))
;; Left-click over the center of a window, but without
;; first exposing it. So if another window covers it, then the
;; click will go to that window instead. Pre-expose defaults to
;; t to ensure that the click goes to the specified window, but
;; it may be useful to pass it as nil as in this example if you
;; are testing that the window is exposed when it should be.
(do-click some-window :pre-expose nil)Function, cg package
Arguments:
This function is never invoked directly by the user. It can be specified as the value of the ide:on-restart property for a project so that when a project EXE is created and the EXE is started, the Allegro CL console appears with instructions displayed on what function(s) to call to continue the EXE initialization. At that point, the console is just a Lisp listener so you can evaluate arbitrary functions to set/determine the initial environment of the EXE while debugging. You can even wrap the functions displayed by the instructions in a call to process-run-function so that the console listener remains active while the application is running.
Function, cg package
Arguments:
This symbol is the default value of the ide:on-restart property of a project. See ide:on-restart for more information. (In earlier releases, this function took a console-state keyword argument.)
Generic Function, cg package
Arguments: window-or-widget-or-handle-or-nil keynum-or-character &key (preview-seconds 0.5)(down-seconds 0.5) shift control alt (down t)(up t)
This generic function is specific to Microsoft Windows, and should not be called on other platforms.
This generic function programmatically emulates pressing and/or releasing a key on the keyboard, after optionally exposing a window and giving it the keyboard focus. This may be useful for automated testing.
The two required arguments window-or-widget-or-handle-or-nil and keynum-or-character.
window-or-widget-or-handle-or-nil may be either a window, a dialog-item, an internal window "handle", or nil. If non-nil, then the specified window or widget and all of its ancestor windows are brought to front, and the window is given the keyboard focus before the keypress is done, so that the specified window will receive it. (If a handle of a window in another application is specified, then it is not possible to give it the keyboard focus programmatically, though do-click can work for that.)
keynum-or-character indicates which key to press and/or release. It may be either the value of one of the "vk-" key constants (see key-names) or the character that appears on one of the alphanumeric keys. If an uppercase character is passed, then a shift is done as if shift were true.
The keyword arguments are:
preview-seconds: may be either a non-negative number indicating the number of seconds to sleep before pressing the key down, or nil to not sleep at all. The default is 0.5.
down-seconds may be either a non-negative number indicating the number of seconds to sleep after pressing the key down but before releasing it, or nil to not sleep at all. The default is 0.5.
shift, control, and alt: if shift is true, then the shift key is pressed before pressing and/or releasing the main key, and released after pressing and/or releasing the main key. control and alt work similarly for the Control and Alt keys.
down and up: If down argument is true, then the key is pressed down. If up is true, then the key is released. If both are true, the key is first pressed and then released. Both are true by default. It would not be useful to pass both as nil.
;; Type a "j" to a window.
(do-keypress some-window #\j)
;; Type a semicolon to whatever window has the keyboard focus.
(do-keypress nil vk-semicolon)
;; Press down the shift key without releasing it.
;; WARNING: Doing this without a subsequent
;; up-click of the same key leaves the OS thinking
;; that the shift key is still down, and a further keystroke
;; will believe it is shifted. This can be fixed interactively
;; by simply pressing and releasing the left shift key.
(do-keypress some-window vk-shift :up nil)
;; Type control-j into a window.
(do-keypress some-window #\j :control t)Generic Function, cg package
Arguments: window-or-widget-or-handle-or-nil object &key (preview-seconds 0.5) (down-seconds 0.5)
This generic function is specific to Microsoft Windows, and should not be called on other platforms.
Calls do-keypress once for each character in a string.
window-or-widget-or-handle-or-nil may be either a window, a dialog-item, an internal window "handle", or nil. This is passed as the window-or-widget-or-handle-or-nil argument to do-keypress.
If object is a string, it is used directly. If it is a symbol, its symbol-name is used as the string. Otherwise a string obtained by calling princ-to-string on object.
The preview-seconds keyword argument to do-keypress will be the preview-seconds to do-keypresses for the first character and as nil for all other characters.
The down-seconds keyword argument to do-keypress will be the down-seconds keyword argument to do-keypresses for the last character and as nil for all other characters.
;; Type a whole string of characters into a window.
(do-keypresses some-window "How about that.")
;; Print an arbitrary object into whatever window has the keyboard
;; focus.
(do-keypresses nil (list :one "Foo"))Macro, cg package
Arguments: (child parent-stream &key result owned-p states) &rest forms
Executes forms (the body) once for each child window of parent-stream, or for each non-child owned window of parent-stream if owned-p is true. child should be a symbol that will be bound to each child (or non-child owned window) during the execution of forms. The value of result is returned from do-windows. This macro avoids consing a list of the windows as the function windows would do, and so may be more efficient in tight loops.
parent-stream may be either a window or the screen. The screen is the value returned by (screen *system*). See screen and *system*.
states may be either nil or a list of any of the window state symbols, :normal, :maximized, :icon, or :shrunk. If states is such a (non-empty) list, then the forms are executed only for windows that are in one of those states. If states is nil, then the forms are executed for all of the windows.
The following form will print the names of all of the top-level windows that are in :normal state (see screen and *system*).
(do-windows (child (screen *system*) :states '(:normal))
(print (name child)))Generic Function, cg package
Arguments: window-or-lisp-widget
Returns whether a window or a lisp-widget uses a memory bitmap to reduce flashing effects when the window is redisplayed. The value may be set either by calling (setf double-buffered) or by passing the :double-buffered initarg when using make-window to create the window or make-instance to create the lisp-widget.
window-or-lisp-widget should be either an instance of basic-pane or one of its subclasses, or an instance of lisp-widget or one of its subclasses. The value should be true to put the window into double-buffering mode, or nil to take it out of double-buffering mode. The default value is nil except for outline and grid-widget, where the default is t.
Double-buffering works by redirecting all drawing function calls to actually draw on the window's internal memory bitmap, and later copying the memory bitmap to the visible window in a single operation. This typically eliminates the flash that occurs when a window is first blanked out before redrawing its content. This flash is often noticable when the user interactively scrolls or resizes a window, or when the application programmatically updates the contents of a window for animation effects.
Drawing is redirected to the memory bitmap only when a drawing function is called inside a redisplay-window method that was called by Common Graphics (rather than the application calling it directly), or when the drawing function is called inside a with-double-buffering macro call. When an application updates the contents of a window, it normally should call invalidate on the window to trigger a redisplay (and then perhaps update-window to force the redisplay to happen immediately), and then Common Graphics will call the window's redisplay-window method. But if you really need to draw directly to a window and would still like double-buffering to occur, then this can be achieved by doing the drawing inside a call to with-double-buffering.
The double-buffered property may not be applied to os-widgets because Common Graphics does not have control over the drawing of them. In addition, the bitmap-pane window and the drawable and multi-picture-button lisp-widgets implement special types of double-buffering, and so this general double-buffering facility may not be used with instances of those classes. (If you do turn the double-buffered property on for them, a warning is signaled and the request is ignored.)
The double-buffered property will automatically create a memory bitmap that is the size of the window's interior, and replace it with a larger one when needed. A bitmap-pane, by contrast, creates a memory bitmap that is the size of the entire scrollable page (or canvas) of the window. So a bitmap-pane is more expensive in terms of memory usage, but will also remember an entire drawing so that the application does not need to redraw it at all when the window is exposed or scrolled.
Creating or resizing a double-buffered window could signal an error of type memory-bitmap-not-created if there is not enough memory for the memory bitmap.
There is a complete code example of using the double-buffered property for animation in the section Animation in cg-drawing.html.
Function, cg package
Arguments: dialog item
This is a possible value for the on-double-click event handler for a control on a dialog with a default-button. It tries to make double-clicking on the control have the same effect as clicking on the default-button. It does this by causing the on-change handler of the default-button to run.
The dialog argument is the dialog and the item argument is the control but this function is not typically called directly.
Generic Function, cg package
Arguments: dialog widget
This function is called whenever a double left click is done on a control that implements double-clicks. The default method calls the on-double-click event-handler function of the control if it has one.
Double-click behavior could be specified for a whole control subclass by adding a double-click-event method rather than giving the same on-double-click event-handler function to every instance of the class.
Generic Function, cg package
Arguments: stream
Returns the double click time for stream in internal time units. The double-click time is the maximum time between clicks for two clicks to be considered a double click rather than two single clicks.
Generic Function, cg package
Arguments: printer
Returns the double-sided property of printer. This property of a printer stream may be specified only as the value of the :double-sided initarg to open-stream. See pop-up-printer-job-dialog for the possible values of this option.
Function, cg package
Arguments:
Returns a list of names indicating the keyboard keys and mouse buttons that were in a pressed-down state when the event that is currently being handled occurred. Each name is either the Lisp character shown on a key or one of the "vk-..." constants that are the value of the constant key-names.
This function operates per-thread. Specifically, keypresses that are done while a window that was created in a particular thread has the keyboard focus will not be included in the list returned by a call that is made to down-key-names in any other thread. (An exception is that if there is a single window hierarchy that contains windows from both threads, then the operating system appears to combine the event queues of the two threads, and down-key-names will still include the keys that were pressed in a window of the other thread.)
Compatibility note: Through version 6.0, the returned list did not include elements for the keys associated with Lisp characters, and included only the vk-... symbols. This was not particularly useful, as it indicated what some but not all the pressed keys were. All keys on standard PC keyboards should now be covered.
See also down-keys, key-is-down-p, key-was-down-p, and mouse-button-state.
Function, cg package
Arguments:
Returns a list of integers indicating the keyboard keys and mouse buttons that were in a pressed-down state when the event that is currently being handled occurred. Each integer is either the char-code of the character shown on a key (thus, (char-code #\A) for the A key) or the value of one of the "vk-..." constants that are the value of the constant key-names.
This function operates per-thread. Specifically, keypresses that are done while a window that was created in a particular thread has the keyboard focus will not be included in the list returned by a call that is made to down-keys in any other thread. (An exception is that if there is a single window hierarchy that contains windows from both threads, then the operating system appears to combine the event queues of the two threads, and down-keys will still include the keys that were pressed in a window of the other thread.)
See also down-key-names, key-is-down-p, key-was-down-p, and mouse-button-state.
Generic Function, cg package
Arguments: widget &key move-values
This operator was modified in release 11.0 by the addition of the move-values argument.
Initiates a dragging operation from widget. The user may "drop" onto another control by clicking the mouse to associate the two controls together in some way. The drag continues until the user "drops" by either pressing a mouse button (if no mouse buttons were down when drag-and-drop was called), releasing a mouse button (if a mouse button was down when drag-and-drop was called), or pressing ESCAPE to cancel the drag. During this time, the mouse cursor changes to indicate whether a drop is allowed at the current mouse cursor location. A drop is allowed whenever the mouse cursor is over a control where droppable-p returns true when called on the dragged control and that dropped-onto control. When the drop is done on the dragged widget, then both droppable-p and droppable-onto-self must return true to allow the drop. The default droppable-p method returns whether the drop-sources property of the dropped-on widget indicates that the drop should be allowed. So an application can enable dragging and dropping either by supplying drop-sources properties or by adding droppable-p methods. By convention, drag-and-drop should not be called for a particular control if
(draggable-p control)returns nil. The default draggable-p method returns true for any control. If the user drops where a drop is allowed, then good-drop is called; if the user drops elsewhere, then bad-drop is called; if the user cancels by pressing ESCAPE, then neither function is called.
The default good-drop method calls drop-put to perform the drop. The built-in drop-put methods typically copy a value from the dragged-from widget to the dropped-on widget, but an application could add drop-put methods for custom dropping behavior. An application will typically add draggable-p methods to determine which controls may be dragged from, droppable-p methods to determine which controls may be dropped onto which, and good-drop methods to process successful drops. drag-and-drop-mouse-moved methods could be added to trigger side effects as the user drags the mouse cursor.
drag-and-drop returns the control that was dropped onto if any, or nil otherwise. There is no dropped-onto control if the user either cancels the drag by pressing ESCAPE or drops at a location that is not over any control. If the dropped-on widget is an item-list widget (and no custom methods are overriding the built-in methods), then the dropped value will be added as a choice in the range of the dropped-on widget, or as multiple choices when the dropped value is a list. And if the move-values argument is true and the dragged-from widget is also an item-list, then the dropped values will also be removed from the range of the dragged-from widget, to effectively move the values rather than copy them. By default, the only visual indication that a drag is taking place is the changing mouse cursor. This is the standard drag-and-drop approach in Windows. But if
(drag-images (configuration *system*))is set to true, then an attempt is made to drag an image of some part of the dragged-from control. (See configuration, *system*, and drag-images.) This image is obtained by calling box-to-drag on the dragged-from control and copying pixels from the screen for that section of the control. box-to-drag methods are supplied for most of the controls to specify the area occupied by the currently selected value of the control. Note that this approach will not work well if the current value of the control is ever scrolled out of view. Depending on which types of controls are being dragged from, these images may or may not be considered sufficiently aesthetic for an application's interface, and so this dragging option should not be used if the result is unsatisfactory. When the IDE is running, a general mouse-left-down method (shown below) causes drag-and-drop to be called if the Alt key is held down and a left click and drag is done on a control. A droppable-p method for the inspector allows dropping arbitrary values from arbitrary controls into inspector slots, and a droppable-p method specializing on both the main IDE toolbar and the extended IDE toolbar allows dragging commands between or within these toolbars. Other than these cases, the IDE does not make use of drag-and-drop, and the methods described in this paragraph exist in the IDE only. Applications must define their own gestures to call drag-and-drop, as well as their own droppable-p methods to define where drops are allowed. The following code implements the IDE's mouse-left-down method for initiating drags. It checks to see if the alt-key is down (but not the control-key or shift-key) and if the mouse cursor was in the interior area of the widget that was clicked. If so, it then initiates a drag, and otherwise it calls the next method.
(defmethod mouse-left-down ((widget dialog-item)
buttons cursor-position)
;; This method exists in the IDE to allow initiating drags
;; by alt-clicking any widget.
(with-boxes (box1)
(case (logand buttons #.(logior control-key shift-key alt-key))
(#.alt-key
(when (and (draggable-p widget)
(inside-box-p cursor-position
(nvisible-box (window widget) box1)))
(drag-and-drop widget)))
(t (call-next-method)))))Applications can add similar methods to initiate drags. Note that while a simple left click could alternately be used to initiate a drag, this should not be done for certain widgets where a mouse-left-down always waits for a mouse-left-up to complete a value selection gesture, since the mouse will not be in a meaningful position for this when the user finally releases the mouse button after dragging; this constraint appears to be limited to the single-item-list and multi-item-list widgets. See also wait-for-drag for another way to decide whether to initiate a drag.
Generic Function, cg package
Arguments: drag-widget object-under-mouse screen-position object-position
This function is called each time the mouse cursor moves during a call to drag-and-drop. The default method does nothing, but an application could add methods if it needs to trigger arbitrary side effects as the user moves the mouse. One example might be to scroll a window in which a drag is intended to be confined if the user moves the mouse outside of that window.
drag-widget is the widget that is being dragged.
object-under-mouse is the widget or window that is currently under the mouse cursor, if any, and nil otherwise.
screen-position is the current mouse cursor position in screen coordinates.
object-position is the current mouse cursor position in the coordinate system of the object-under-mouse if it is non-nil, and otherwise is nil.
Generic Function, cg package
Arguments: dialog-item
Returns the mouse cursor image to be used while doing a drag from dialog-item while the mouse cursor is not over a dialog-item. (This cursor is also shown before the mouse cursor first moves off of the widget from which dragging is being done.)
An application typically would not need to call this generic function, but may define methods on it to customize the mouse cursors that are used by drag-and-drop. The returned value should be either an instance of the cursor class or a mouse cursor handle.
The default method returns the mouse cursor handle which is the value of the variable no-drop-cursor. This cursor shows a red circle with a diagonal line through it, indicating that it is generally not possible to drop when not over a dialog-item.
drop-cursor and no-drop-cursor return mouse cursors suitable for use during a drag.
Generic Function, cg package
Arguments: configuration
When doing a drag-and-drop, the image of what is being dragged can move with the mouse, or not, as this property of configuration is true or nil. The current configuration is the value of (configuration *system*) (see configuration and *system*).
drag-images is a property of the configuration class.
Generic Function, cg package
Arguments: dialog-item
When this widget property is true, a drag-and-drop will be initiated from the widget whenever the user holds down the Alt key while left-clicking the widget. This is a quick alternative to writing custom code that makes a command or gesture call drag-and-drop. (The generic function draggable-p must also return true, though the default method always does that.)
There are some special considerations when the widget is an item-list, that is a single-item-list or a multi-item-list. The Alt+LeftClick will not select the clicked value before initiating the drag, mainly because in a multi-item-list that would deselect multiple values that had been selected for dragging. So the user must first select the value(s) to drag, and then do the Alt+LeftClick to do the drag. (Using the Alt key allows the Control and Shift keys to still work for selecting or toggling multiple values as usual.) If the Control key is used along with the Alt key and a successful drop is done into another item-list, then the values will be removed from this widget at the end, thereby moving the values from this widget to the dropped-on widget rather than copying them.
In the IDE, a mouse-left-down:around method makes an Alt+LeftClick on any widget call drag-and-drop. So you would not need to set this property to true when testing a project in the IDE (except for the special Control+Alt+LeftClick case), but you would need it in a standalone application that you generate from a project.
Generic Function, cg package
Arguments: list-view
This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.
Returns the value of the draggable-headers property of a list-view control. The value may be set at creation time by passing the :draggable-headers initarg to make-instance, or any time later by calling (setf draggable-headers).
This property specifies whether the user can drag list-view column headers horizontally to change their order. The value can be nil or true. The default is nil.
Generic Function, cg package
Arguments: drag-from-widget
Should return true if drag-from-widget can be dragged. (The default method does and other added methods should behave that way as well.)
The default method allows for dragging from any control. You may want to redefine this default method to return nil and then add specific methods to return t where dragging is allowed.
Generic Function, cg package
Arguments: split-bar
Returns the dragging-thickness property of a split-bar widget. The value may be set at creation time by passing the :dragging-thickness initarg to make-instance, or any time later by call (setf dragging-thickness).
This is the visible thickness of the split-bar widget while it is being dragged, measured in pixels. The value should be a non-negative integer. The default value is 3, to draw a dragging line that's thinner than the mouseable thickness. The value may be set at creation time by passing the :dragging-thickness initarg to make-instance, or any time later by call (setf dragging-thickness).
The mouseable thickness is specified with the bar-thickness property.
Function, cg package
Arguments: stream from-pos to-pos &key (length 20) (width 10) fill
draw-arrowhead draws a simple arrowhead at to-pos for a line that was drawn between from-pos and to-pos.
The returned values indicate the point on the line at the base of the arrowhead. This could be used to draw the associated line so that it ends at this point instead of at the tip of the arrowhead, in order to leave a sharper tip when the line is thick. There are two returned values, for the x and y coordinates or the point.
While you can draw the line first and then draw arrowheads at one or both ends, you can also draw the arrowheads first, capturning the base coordinates and then draw the line with one end the base coordinates and thus ensure the tip of the arrowhead is sharp.
The arguments are:
stream: the window or other graphical stream on which to draw the arrowhead. stream should be a cg-stream.
from-pos: a position object (see make-position) indicating the "other" end of a line that was drawn, so that the arrow will be drawn at the proper angle.
to-pos: a position object (see make-position) indicating the tip of the arrowhead.
length: the length of the arrowhead in streamq units (which are usually pixels). The default is 20.
width: the width of the arrowhead at its base in stream units. The default is 10.
fill: either nil, t, an RGB color object (see make-rgb), or an HLS color (see make-hls). This argument indicates how the arrow is to be filled.
If the value is nil (the default), the arrow is filled in the current background-color of the stream. This creates the effect of a hollow arrow (with the background color showing through the arrowhead), though in fact the interior is still filled in order to cover over the end of the actual line that was drawn beforehand.
If the value is t, then the arrow is filled with the current foreground-color of the stream, which is the color that is always used to draw the border of the arrowhead; this creates a solid arrow.
If the value is an RGB or HLS color object, then the arrowhead is filled with that color. This option may be used to fill the arrowhead with a different color than is used for the border of the arrowhead.
Here is an example function that draws arrows at various angles.
(defun test-arrowheads (&key (length 20)(width 10))
(let* ((window (make-window :arrows
:class 'bitmap-window
:title "Arrowheads"
:interior (make-box 200 200 600 600)
:scrollbars nil))
(pane (frame-child window))
(center #.(make-position 200 200))
coord side)
(with-positions (pos1)
(dotimes (j 9)
(setq coord (+ 200 (* 40 (- j 4))))
(dolist (fill (list nil t))
(setq side (if fill 360 40))
(nmake-position pos1 side coord)
(draw-line pane center pos1)
(draw-arrowhead pane center pos1 :fill fill
:length length :width width)
(nmake-position pos1 coord side)
(draw-line pane center pos1)
(draw-arrowhead pane center pos1 :fill fill
:length length :width width))))))See also cg-drawing.html.
Generic Function, cg package
Arguments: split-bar
Returns the draw-at-dragging-thickness property of a split-bar widget. The value may be set at creation time by passing the :draw-at-dragging-thickness initarg to make-instance, or any time later by call (setf draw-at-dragging-thickness).
This property indicates whether to draw the split-bar at the typically thinner dragging-thickness even when the split-bar is idle and it has a thicker mousable area (see bar-thickness). The value should be nil or true. The default value is nil. The value may be set at creation time by passing the :draw-at-dragging-thickness initarg to make-instance, or any time later by call (setf draw-at-dragging-thickness).
Generic Function, cg package
Arguments: stream vertices
The function was named draw-curve is releases prior to 8.0. The new name is more descriptive and less likely to conflict with a user function name. The behavior has not changed.
Draws one or more Bezier curves on stream. vertices should be a sequence (list or vector) of positions (see make-position) that indicate the starting, ending, and control points for the curves. Each curve is specified by four positions that indicate a starting point, two control points, and an ending point in that order. The ending point of each curve is re-used as the starting point of the next curve, and so vertices must contain (1+ (* 3 N)) to draw N curves (where N must be at least 1). For example, to draw two connected curves you need to pass a sequence of 7 positions, where positions 1 through 4 specify the first curve and positions 4 through 7 specify the second.
stream should be a cg-stream.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream box
Draws box on stream. box must be a box object, such as created by make-box. stream should be a graphical-stream.
To use individual coordinates rather than creating position objects, see draw-box-x-y.
See also erase-box and cg-drawing.html.
Generic Function, cg package
Arguments: stream left top right bottom
Draws a rectangle on stream from an upper-left position at (left, top) to a lower-right position at (right, bottom). stream should be a graphical stream. The other arguments should be integers. To use a box object rather than individaul coordinates, see draw-box.
Generic Function, cg package
Arguments: stream offset
Draws on stream a line from the current position to the position offset away from current position. offset should be a position (see make-position). stream should be a graphical-stream.
Contrast with draw-to and draw-to-x-y which draw from the current position to the argument location.
To use individual coordinates rather than creating position objects, see draw-by-x-y.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream x y
Draws a line from the current position in stream to a position that is x pixels to the right of the current position and y pixels downward from the current position. stream should be a graphical-stream. x and y should be integers. To use a position object rather than individual coordinates, see draw-by.
The current position may be set by calling move-to-x-y.
Generic Function, cg package
Arguments: row column row-num column-num cell-box stream
Called for drawing the interior of each individual cell of a grid (see grid-widget class). If not using one of the built-in widget column types, then supply a draw-cell method to draw your custom cell. cell-box is the region within stream that contains the interior of the cell, so you should draw only within that area of stream.
Here is the default method, which is used for any cell not handled either by one of the special built-in grid-column types such as combo-box-column-mixin or by an application-defined draw-cell method. It simply draws the printed representation of the cell's value. Note that it calls read-cell-value to find the value to draw for this particular cell; this is the suggested approach, though the draw-cell method may determine what to draw by whatever means is suitable to the application. The default mthod calls cell-horizontal-padding, cell-vertical-padding, cell-horizontal-justification, cell-vertical-justification, cell-wrapped-p, data-read-converter, draw-string-in-box, inflate-box, and read-cell-value.
(defmethod draw-cell ((row grid-row)(column grid-column)
row-num column-num cell-box stream)
(let* ((converter (or (data-read-converter column) #'identity))
(value (funcall converter
(read-cell-value
row column row-num column-num))))
(when value
(draw-string-in-box
stream (princ-to-string value) nil nil
(inflate-box cell-box
(- (cell-horizontal-padding row column))
(- (cell-vertical-padding row column)))
(cell-horizontal-justification row column)
(cell-vertical-justification row column)
nil (cell-wrapped-p row column)))))Common Graphics will call draw-cell any time a grid cell gets partly uncovered or is invalidated (such as by calling invalidate-cell or invalidate-section), so an application need not call it.
A draw-cell method often calls read-cell-value to retrieve the value that should be displayed in the cell. Otherwise it may call the data-reader of the column and/or directly access the data-object of the row to find the value. Those techniques are handy if the grid follows the common paradigm where each grid row represents a data object and each grid column represents an attribute of those objects. Otherwise, a draw-cell method may use a completely custom technique for determining the value to draw, keying in some way off of the names or types of the row and column or the sub-row and sub-column indices.
Even if you are not using the built-in cell widgets such as those provided by editable-text-column-mixin or combo-box-column-mixin, you still likely won't need to write custom draw-cell methods for cells that simply display a string for the value you are returning from a read-cell-value method. And if you need to modify the way in which the default draw-cell method draws the string, you can alternately do that by writing methods on generic functions such as cell-background-color, cell-font, and cell-vertical-padding.
Before Common Graphics calls draw-cell, it will first set the current font of the stream to be the font that's returned by cell-font. It will also set the current foreground-color and background-color of the stream to be the values returned by cell-foreground-color and cell-background-color, and fill the cell with the background color. So a custom draw-cell method does not need to handle those aspects of the drawing.
See also draw-cell-focus.
Generic Function, cg package
Arguments: grid-row grid-column stream cell-box
Draws something in a grid cell to indicate that that cell currently has the keyboard focus (and so a keypress will result in a call to cell-key-down for that row and column). The default method draws a one-pixel thick line at the outer edge of the cell's interior.
Applications should not call this function, which is called automatically, but may add methods to override the default focus drawing style.
This function is called once to draw the focus and again in the same way to erase it. The paint-operation of the stream is always temporarily set to po-invert when draw-cell-focus is called, so that drawing the same thing a second time will erase what was drawn. This means that a draw-cell-focus method should never set the paint-operation to something else, as this would prevent the erasure from working. It is also probably not useful to set the foreground-color in a draw-cell-focus method, as it is not feasible to predict the color that will result when the official foreground color is combined with the current screen colors via the po-invert operation.
grid-row and grid-column indicate the cell in which focus is to be drawn. stream is the stream on which the drawing should be done, and cell-box is the box on stream that encompasses the interior of the cell. The method may modify the box if desired. A draw-cell-focus method may draw outside this box, but the clipping-box of stream is set to the grid section that contains the cell when this function is called, so that any drawing outside the whole section will be clipped.
Here is the default method:
(defmethod draw-cell-focus ((row grid-row)(column grid-column)
stream cell-box)
(decf (box-right cell-box))
(decf (box-bottom cell-box))
(with-line-width (stream 1)
(draw-box stream cell-box)))See also draw-cell.
Generic Function, cg package
Arguments: stream center radius
Draws a circle with the radius and center specified on stream stream should be a cg-stream. center must be a position (see make-position).
See also erase-circle.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream center radius start-angle length-angle
Draws on stream a circle-arc, starting at start-angle and subtending length-angle, with the radius and center as specified.
Angles are measured clockwise starting from the positive x-axis (taking the center as the origin). Thus start-angle 0 is the due East point if the circle is thought of as a compass. start-angle 0 and length-angle 90 draws the arc from due East to due South. The endpoint coordinates may be determined by calling ellipse-start-and-end.
center should be a position (see make-position). stream should be a cg-stream.
See also erase-circle-arc.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream center radius start-angle length-angle
Draws on stream a circle-sector, that is an arc and the bounding radii to produce a shape like a piece of pie, starting at start-angle and subtending length-angle, with the radius and center as specified.
center must be a position (see make-position). stream should be a cg-stream.
Angles are measured clockwise starting from the positive x-axis (taking the center as the origin). Thus start-angle 0 is the due East point if the circle is thought of as a compass. Start-angle 0 and length-angle 90 draws the lower right quarter, now thinking of the circle as a pie. The endpoint coordinates may be determined by calling ellipse-start-and-end.
See erase-circle-sector.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle
Draws an ellipse on stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise.
center should be a position (see make-position). stream should be a cg-stream.
The following example creates a window that draws a thin vertically-oriented ellipse that is 200 pixels tall and has a line-width of 3 pixels:
(defclass ellipse-window (frame-window)()
(:default-initargs
:exterior (make-box-relative 100 100 100 400)
:title "Ellipse"))
(defmethod redisplay-window ((window ellipse-window)
&optional clipping-box)
(declare (ignore clipping-box))
(call-next-method) ;; Draw the background
(with-line-width (window 3)
(draw-ellipse window (make-position 50 150) 100 20 90)))
(make-window :ellipse-example :class 'ellipse-window)See also cg-drawing.html.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle start-angle length-angle
Draws an ellipse arc on stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center.
Angles are measured in degrees clockwise from the 3 o'clock position. The endpoint coordinates may be determined by calling ellipse-start-and-end.
So, the ellipse created when specifying semi-major-axis 200, semi-minor-axis 10, and semi-major-axis-angle 90 is a long, thin ellipse, 400 pixels wide, with the long axis vertical, centered at center. Now, with a start-angle of 0 and a length-angle of 90, all of the ellipse in the lower right quadrant is drawn and no part is drawn in any other quadrant.
center should be a position (see make-position). stream should be a cg-stream.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle start-angle length-angle
Draws an ellipse sector on stream. An ellipse-sector is an ellipse-arc with the endpoints of the arc connected to the center of the ellipse, like a piece of an elliptical pie.
The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center.
Angles are measured in degrees clockwise from the 3 o'clock position. The endpoint coordinates may be determined by calling ellipse-start-and-end.
So, the ellipse created when specifying semi-major-axis 200, semi-minor-axis 10, and semi-major-axis-angle 90 is a long, thin ellipse, 400 pixels wide, with the long axis vertical, centered at center. Now, with a start-angle of 0 and a length-angle of 90, all of the ellipse in the lower right quadrant is drawn, along with the lines from the ends of the arc to the center and no part is drawn in any other quadrant.
center should be a position (see make-position). stream should be a cg-stream.
See also cg-drawing.html.
Generic Function, cg package
Arguments: widget
draw-focus returns whether a focus rectangle is drawn in a multi-picture-button, picture-button, static-picture, scrolling-static-text, or chart-or-plot. The value may be set at creation time by passing the draw-focus initarg, or any time later by calling (setf draw-focus).
The value may be true or nil. The default is t except for multi-picture-button, where it is nil.
If true, then when the widget has the keyboard focus it draws a focus rectangle around the particular button that has the focus within the widget. Pressing the spacebar will then press or unpress that button. The arrow keys will move the focus to other buttons, scrolling as needed, and clicking on a button will move the focus to that button.
If nil, then no focus rectangle is drawn, and pressing the spacebar will not press a button because no particular button has the keyboard focus. Clicking the mouse on buttons will still press and unpress them.
When the draw-focus property of a scrolling-static-text is true and the widget has the keyboard focus, then a focus rectangle is drawn that overrides the rectangle that would be drawn by the border-color property, if any. This focus rectangle will use the system-edge-shadow-color unless the usual border-color is that same color, in which case the focus rectangle will be black.
Generic Function, cg package
Arguments: grid-widget clipping-box grid-back-color &key *printer (left 0) (top 0)
Called for drawing the whole grid. Might be desirable to wrap this method.
Generic Function, cg package
Arguments: grid-widget row-section column-section clipping-box grid-back-color stream &key (left 0) (top 0)
Called for drawing each cross-section of row-section and column-section for a grid; might be desirable to wrap this method.
Generic Function, cg package
Arguments: chart-view
Returns the value of the draw-high-low-values property of a chart-view. The value may be set at creation time by passing the draw-high-low-values initarg, or any time later by calling (setf draw-high-low-values).
A boolean value indicating whether any :high-value and :low-value data values in a chart-widget are currently drawn. The default value is t.
This property could be toggled on and off to view different parts of the data at different times.
See set-chart-value for an explanation of high and low values. An alternative is to use the value-types property.
See also high-low-value-style.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: stream icon position &key width height standard-size
Draws icon on stream at position. stream should be a graphical-stream. icon should be an icon handle (an integer), as returned by extract-icon-from-file or create-icon-handle. position should be the position on the stream at which to draw the upper-left corner of the icon.
If width, height, and standard-size are all nil (as they are by default), then the icon is drawn at the size at which it was created. If standard-size is true, then it is drawn at the standard (larger) size for icons on that platform. Otherwise width and/or height may be specified as a positive integer to indicate a size in pixels that overrides the default for that dimension.
See cg-icons.html.
Generic Function, cg package
Arguments: object
draw-icons is a property of the outline and dropping-outline classes. It is also a property of icon-drawing-views, which are associated with the chart-or-plot.
Returns the value of the draw-icons property of outline. This property determines whether to draw pixmaps to the left of each item in the outline control.
Returns the value of the draw-icons property of a icon-drawing-view. The value may be set at creation time by passing the draw-icons initarg, or any time later by calling (setf draw-icons).
A boolean value indicating whether icons are drawn at the data points of a icon-drawing-view in a chart-or-plot. The default value is t.
Either this property or draw-lines (or both) should be true, because otherwise nothing would be drawn for the data values. The icon-images property should also contain a non-null list of icons to draw, when this property is true.
See also icon-line-widths, icon-sizes, icon-fill-colors, and icons-filled.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the draw-legend property of a chart-or-plot. The value may be set at creation time by passing the :draw-legend initarg, or any time later by calling (setf draw-legend).
draw-legend indicates whether a legend is drawn in a chart-or-plot. The legend is a table at the bottom of the chart with a descriptive string for each chart object and a visual indication of which graph line or set of bars represent it. The chart-or-plot will automatically make room for the legend whenever it is drawn.
The value may be t to draw the legend, nil to not draw it, or :when-multiple-objects to draw the legend if and only if there are multiple objects in the chart-objects property. The default value is :when-multiple-objects, since a legend is typically needed only to differentiate multiple chart objects.
The legend will be drawn according to properties of the chart-legend instance that is in the chart-legend property of the chart-or-plot.
See chart-widget, plot-widget, and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the draw-legend-border property of a chart-legend. The value may be set at creation time by passing the draw-legend-border initarg, or any time later by calling (setf draw-legend-border).
A boolean value indicating whether a border rectangle is drawn around the chart-legend in a chart-widget. The default value is t.
This property is used only when the draw-legend property of the chart-widget is true.
See also border-color, interior-horizontal-margin, and interior-vertical-margin.
See chart-widget and also .
Generic Function, cg package
Arguments: stream from to
Draws a line on stream from from to to (from and to must be position objects, as created by make-position). stream should be a graphical-stream.
If from and to are the same and line-width is 1, nothing will be drawn. You can draw a single pixel using the pixel function.
To use individual coordinates rather than creating position objects, see draw-line-x-y.
See also erase-line.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream x1 y1 x2 y2
Draws a line on stream from (x1, y1) to (x2, y2). stream should be a graphical-stream. The other arguments should be integers. To use position objects rather than individual coordinates, see draw-line.
Generic Function, cg package
Arguments: object
draw-lines is a property of the outline and dropping-outline classes. It is also a property of line-drawing-views, which are associated with the chart-or-plot widgets.
Returns the value of the draw-lines property of object. This property determines whether or not an outline control will have long vertical and short horizontal lines graphically depicting the hierarchy of the outline.
Returns the value of the draw-lines property of a line-drawing-view. The value may be set at creation time by passing the draw-lines initarg, or any time later by calling (setf draw-lines).
A boolean value indicating whether graph lines are drawn for a line-drawing-view in a chart-or-plot. The default value is t.
Either this property or draw-icons (or both) should be true, because otherwise nothing would be drawn for the data values.
For a chart-widget, this property and other line-drawing-view properties are used only when the chart-view property of the chart-widget is :line to display the line-graph-view.
See also line-colors, line-widths, line-dashings, and span-missing-items.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the draw-major-grid-lines property of a chart-axis. The value may be set at creation time by passing the :draw-major-grid-lines initarg, or any time later by calling (setf draw-major-grid-lines).
A value indicating whether (and how) grid lines are drawn for the major tic positions of a chart-axis in a chart-widget.
When drawn, a grid line extends across the body of the chart, perpendicular to the axis with which it is associated.
Here are the possible values:
nil - Major grid lines are not drawn. This is the default value.
t - Major grid lines are drawn, and are drawn at the major tic positions.
:after - Each major grid line is drawn midway between its major tic position and the next major tic position. This may be especially useful for delimiting groups of non-stacked bars by drawing lines between the groups, for example, rather than drawing a line through the middle of each group of bars. This choice is probably not aesthetic when draw-minor-grid-lines is true.
:before - Like :after, except that each grid line is drawn between its official position and that of the previous grid line.
:between - Like :after and :before except that no grid line is drawn before the first major tic position or after the last one.
See also major-grid-line-color, major-grid-line-dashing, major-grid-line-width, and draw-minor-grid-lines.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-axis
Returns the value of the draw-major-labels property of a chart-axis. The value may be set at creation time by passing the :draw-major-labels initarg, or any time later by calling (setf draw-major-labels).
A value indicating whether (and how) label strings are drawn for the major tic positions of a chart-axis in a chart-widget. Here are the possible values:
nil - No labels are drawn for major tic positions.
t - Labels are drawn for major tic positions, and are drawn directly outward from each tic position. This is the default value.
:after - Each major tic label is drawn midway between its major tic position and the next major tic position. This can be useful if the label actually refers to the span between the two tics. For example, if there is a major tic for each year and a minor tic for each month, then printing the year in the :after position for the major tic for the beginning of the year will print the year in the middle of the minor tics for the months of that year.
:after-nestled - This is like :after, except that it will print the string closer to the axis if the minor-tic-length is less than the major-tic-length. It assumes that the label will fit between the major tic marks and therefore need only avoid overlapping the minor tic marks.
:before - This is like :after, except drawing the label between its tic position and the previous major tic position.
:before-nestled - This like like :before in the way that :after-nestled is like :after.
See also on-print-major-label, draw-major-tics, major-label-color, major-label-font, major-label-frequency, major-label-frequency-offset, major-label-min-spacing, major-label-wrapping, overlap-major-and-minor-labels, and draw-minor-labels.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the draw-major-tics property of a chart-axis. The value may be set at creation time by passing the :draw-major-tics initarg, or any time later by calling (setf draw-major-tics).
A value indicating whether (and how) tic marks are drawn for the major tic positions of a chart-axis in a chart-widget. Here are the possible values:
nil - Major tic marks are not drawn.
t - Major tic marks are drawn, and are drawn at the major tic positions. This is the default value.
:after - Each major tic mark is drawn midway between its official position and the position of the next major tic mark. This may be useful for delimiting groups of non-stacked bars, for example, rather than pointing to the middle of each group of bars. This choice is probably not aesthetic when draw-minor-grid-lines is true.
:before - Like :after, except that each tic mark is drawn between its official position and that of the previous tic mark.
:between - Like :after and :before except that no tic mark is drawn before the first major tic position or after the last one.
See also draw-major-labels, major-tic-length, major-tic-width, major-tic-increment, and draw-minor-tics.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-axis
Returns the value of the draw-minor-grid-lines property of a chart-axis. The value may be set at creation time by passing the :draw-minor-grid-lines initarg, or any time later by calling (setf draw-minor-grid-lines).
A value indicating whether (and how) grid lines are drawn for the minor tic positions of a chart-axis in a chart-widget. The possible values are the same as for draw-major-grid-lines, though they refer to the minor tic positions rather than the major ones. The default value is nil.
A minor grid line is not drawn if a major grid line is drawn in the same place.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the draw-minor-labels property of a chart-axis. The value may be set at creation time by passing the :draw-minor-labels initarg, or any time later by calling (setf draw-minor-labels).
A value indicating whether (and how) label strings are drawn for the minor tic positions of a chart-axis in a chart-widget. The possible values are the same as with draw-major-labels, though they refer to the minor tic positions rather than to the major ones, and the "nestled" options do not have a distinct effect. The default value is t.
A minor label is not drawn at a major tic position if a major label or a major tic mark is drawn there (and not offset to one side) and the overlap-major-and-minor-labels property is true. Whether this conflict exists depends on the values of draw-major-labels, draw-minor-labels, and draw-major-tics.
See also on-print-minor-label, minor-label-color, minor-label-font, minor-label-frequency, minor-label-frequency-offset, minor-label-wrapping, and major-label-min-spacing.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-axis
Returns the value of the draw-minor-tics property of a chart-axis. The value may be set at creation time by passing the :draw-minor-tics initarg, or any time later by calling (setf draw-minor-tics).
A value indicating whether (and how) tic marks are drawn for the minor tic positions of a chart-axis in a chart-widget. The possible values are the same as with draw-major-tics, though they refer to the minor tic positions rather than to the major ones. The default value is nil.
A minor tic mark is not drawn at a major tic position if a major tic mark is drawn there (and not offset to one side).
See also minor-tics-per-major-tic, minor-tic-increment, minor-tic-length, and minor-tic-width.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: object printer-stream &key left top
Prints object on printer-stream at left, top from printer-physical-offset of the printer.
Currently the grid-widget, outline, and chart-widget controls implement methods for this generic function, so that they may be drawn in high resolution at an arbitrary position in printed output. Other windows or widgets could be copied directly from the screen to a printer stream by calling copy-stream-area (or get-pixmap followed by copy-to-stream), but that would simply copy the screen pixels rather than redrawing the object at the typically higher resolution of the printer. If an application implements a custom control (by defining a subclass of lisp-widget and supplying Lisp code for drawing it and handling mouse clicks and so on), then a draw-on-printer method could be written for the control.
The following example will draw the Employee Grid example from the Navigator dialog on a printer, using the printer's high resolution. First run the Employee Grid example and then evaluate the following form to print it.
(let* ((dialog (find-window :employee-chart))
grid)
(unless dialog
(error "Run the Employee Grid-Widget example first."))
(setq grid (find-component :employee-grid dialog))
;; Open a printer stream at 100 stream units per inch,
;; which approximates the resolution of a computer screen,
;; and find the usable drawing area between the margins.
(with-output-to-printer (out :units-per-inch 100)
(let* ((left-margin (left-margin out))
(right-margin (right-margin out))
(top-margin (top-margin out))
(bottom-margin (bottom-margin out)))
;; Draw a horizontally centered title.
(with-font (out (make-font-ex nil "Arial" 24))
(draw-string-in-box
out "Employee Information" nil nil
(make-box left-margin top-margin right-margin
(+ top-margin 30))
:center :top))
;; Draw the employee grid centered horizontally, and
;; a little below the title.
(draw-on-printer grid out
:left (+ left-margin
(floor (- right-margin left-margin
(width grid))
2))
:top (+ top-margin 100)))))Generic Function, cg package
Arguments: outline
Returns the value of the draw-plus-minus property of outline. This property determines whether to draw the plus and minus symbols beside each item in the outline control's dialog. If drawn, a minus indicates that all of the immediate descendents of an item are displayed while a plus means that there are undisplayed descendents.
draw-plus-minus is a property of the outline and dropping-outline classes.
Generic Function, cg package
Arguments: stream vertices
Draw on stream the polygon specified by vertices, which should be a sequence (list or vector) of positions (see make-position). A line is drawn connecting the first vertex with the final vertex.
stream should be a cg-stream.
Contrast with draw-polyline, which does not connect the first and last vertices.
See also cg-drawing.html.
Generic Function, cg package
Arguments: stream vertices
Draws on stream lines connecting the positions in vertices, which should be a sequence (list or vector) of positions (see make-position). stream should be a cg-stream.
The first and last vertices are not connected. Contrast with draw-polygon, which does connect the first and last vertices.
See also cg-drawing.html.
Generic Function, cg package
Arguments: plot-view
Returns the draw-regression-lines property of a plot-view object, which is associated with a plot-widget control. The value may be set at creation time by passing the :draw-regression-lines initarg to make-instance, or any time later by calling (setf draw-regression-lines).
This is a boolean value (nil or true) indicating whether to draw a regression line for each of the chart-objects of the plot-widget. When drawn, each regression line will be a straight line segment that minimizes the sum of the squares of vertical distances between the plotted points for one chart object and the regression line itself. The default value is nil, and so no regression lines are drawn by default.
The line styles that are used to draw the regression lines may be specified with the regression-line-colors, regression-line-dashings, and regression-line-widths properties.
Generic Function, cg package
Arguments: stream top-left width height corner-width corner-height
Draws a rounded box on stream with top-left, width, and height indicated. A rounded box has rounded corners. The corner-width and corner-height arguments indicate the width and height of an ellipse that is used to draw the corners (and so the corners themselves are actually only half that wide and tall).
stream should be a cg-stream.
See also fill-rounded-box and erase-rounded-box.
See also cg-drawing.html.
Generic Function, cg package
Arguments: grid-widget section box stream
Draws something arbitrary in the scrollbar-area of a non-scrollable grid-widget section. When a row-section or column-section's scrollbars property is nil, then a scrollbar is not displayed for the section, leaving a blank space where the scrollbar would have been.
If an application would like to make use of this space, it can supply a draw-scrollbar-area method for the grid-widget and section in question. stream is the grid-widget sub-window on which to draw, and box is the area of this sub-window in which to draw.
Generic Function, cg package
Arguments: stream string start end box horizontal-justification vertical-justification &optional string-vertical-p wrap-p calculate-height no-clip
If calculate-height is nil (the default), this function draws all or part of string in box on stream with the specified formatting options. The string is clipped as necessary to prevent it from extending outside the box. The string is wrapped at spaces if wrap-p is true. See below for more information on wrap-p. This function returns the height of the wrapped text that was drawn, in pixels. This value is useful when the wrap-p argument is true, since it is hard to predict how many lines of text will result from the wrapping.
If calculate-height is specified true, then the text is not drawn, but the height necessary if it were drawn is returned. This information may be useful for determining how much space is needed to draw particular pieces of text.
The start and end arguments specify the starting and ending locations of the portion of the string to be drawn. These are not optional arguments. The values must be non-negative integers or nil. To get the whole string drawn, specify 0 or nil and (length string) or nil as the values.
box should be a box object (as made with make-box). It denotes the rectangular region of the stream into which to fit the string.
stream should be a cg-stream.
The remaining arguments are as follows:
horizontal-justification can be one of :left, :right, :center, :fill. Any other value (including nil) is taken to mean :left. If :fill, then the wrap-p argument is coerced to nil and extra space is added at the space characters in the string to stretch the string as a single line of text to fill the entire width of the specified box.
vertical-justification can be one of :top, :bottom, :center. Any other value (including nil) is taken to mean :top. If the wrap-p optional argument is specified and true, vertical-justification is :top regardless of what value is specified.
string-vertical-p: the functionality associated with this argument is unimplemented and the value is ignored.
wrap-p: this optional argument is a Boolean which specifies whether text should be wrapped in the box. If specified true, then the string will be wrapped (at space characters) into multiple lines, each fitting horizontally into the specified box. All wrapping occurs at spaces. When this argument is true, vertical-justification is :top (regardless of what is specified). Note that newline characters in string always cause a wrap to the next line whatever the value of wrap-p.
no-clip: if true, then the string is not clipped as usual at the edges of the specified box, and so the string will extend off the right or bottom edge of the box if it is too long to fit within the box. Even if the general non-clipping behavior is not a problem, using this option may also be useful for avoiding an apparent Windows glitch where part an uppercase W will be clipped off the left edge of the box in certain fonts.
Each character printed can be surrounded by a rectangle large enough to contain the character. When a character is printed, what should happen to this surrounding rectangle? There are two choices: it should be colored in with the window background-color, or it should be untouched, so that only the pixels associated with the character itself are modified. See transparent-character-background for information on how the background pixels of each character cell are drawn.
An alternative to draw-string-in-box is to call Common Lisp stream output functions such as format or princ, which work on Common Graphics windows and other graphical-streams because they are set up as Lisp streams. These functions will position the upper-left corner of the string at the current-position of the stream. In particular, draw-string-in-box is not suitable when the current font of the stream has a non-zero font-angle, because the text will be rotated about its upper-left corner and will therefore extend outside the specified box. If you call the lower-level functions write-string, write-char, and write-sequence on a Common Graphics stream, then you should call force-output or finish-output before subsequently calling any graphics-related functions; see the note at the end of Common Graphics Streams in cgide.html.
Function, cg package
Arguments: stream pathname-or-string &key font left-margin-in-pixels right-margin-in-pixels newline-spacing-in-lines just-return-text-height-p
Draws the contents of the text file identified by pathname-or-string onto stream, which should be a cg-stream and is typically a graphical window. Drawing begins at the current y position indented left-margin-in-pixels. The total pixel height of the drawn text is returned.
font specifies the font to use to write the text. Defaults to the font of stream.
left-margin-in-pixels, measured from the left margin, and right-margin-in-pixels, measured from the right margin, bound the drawing of the string. Both default to 0. Note again that the arguments add space in addition to the current margins of stream.
If newline-spacing-in-lines is specified, it should indicate the number of lines to skip when an explicit newline appears in string. The appearance will then differentiate between newlines caused by wrapping and those caused by explicit newlines. The value can be a floating-point number. Defaults to 0.5.
If just-return-text-height-p is specified true, no drawing is done but the height needed for the drawing is calculated and returned.
Generic Function, cg package
Arguments: stream to
Draws a line on stream from the current position to to, which must be a position (see make-position). stream should be a cg-stream.
The to position becomes the new current position. Contrast with draw-by, where a line is drawn to an offset relative to the current position rather than an absolute position as with this function.
See also draw-to-x-y and cg-drawing.html.
Generic Function, cg package
Arguments: stream x y
Draws a line on stream from its current-position to the position specified by x and y. A call to draw-to-x-y would typically be preceded by a call to move-to-x-y, or by another call to draw-to-x-y (which sets the current-position of the stream to be the position to which it drew).
draw-to-x-y is like draw-to, but does not require first creating a position object from the individual x and y coordinates.
stream is an instance of a subclass of graphical-stream.
x is the horizontal coordinate, measured rightward in pixels in the stream's scrollable page (canvas).
y is the vertical coordinate, measured downward in pixels in the stream's scrollable page (canvas).
See also cg-drawing.html.
Function, cg package
Arguments: stream string &key font left-margin-in-pixels right-margin-in-pixels newline-spacing-in-lines stream-width just-return-text-height-p
Draws string on stream at the current position (see current-position), wrapping at spaces as needed to fit within the margins. Returns the total pixel height of the printed text.
stream should be a cg-stream.
font specifies the font to use to write the text. It defaults to the font of stream, the value of font applied to stream.
left-margin-in-pixels, measured from the left edge, and right-margin-in-pixels, measured from the right edge, bound the drawing of the string. Both default to 0.
If newline-spacing-in-lines is specified, it should indicate the number of lines to skip when an explicit newline appears in string. The appearance will then differentiate between newlines caused by wrapping and those caused by explicit newlines. The value can be a floating-point number. It defaults to 0.5.
If stream-width is specified, it overrides right-margin-in-pixels. The text will be this width.
If just-return-text-height-p is specified true, no drawing is done but the height needed for the drawing is calculated and returned.
Generic Function, cg package
Arguments: drawable-bitmap-stream
Returns the drawable control with which the specified drawable-bitmap-stream is associated.
Function, cg package
Arguments: drawable
Returns the stream that an application should currently draw on for a drawable. If the use-bitmap-stream property of drawable is true, drawable-stream will return the bitmap-stream of drawable. Otherwise, drawable-stream will return the visible window of the drawable control.
Note that if drawable is not currently on a dialog and use-bitmap-stream is false, then nil is returned. This may cause problems since the appropriate stream is passed automatically to the drawing functions.
Generic Function, cg package
Arguments: window
This generic function is used only in CG/JS mode, though it is available everywhere for cross-platform code.
The default method returns nil, but an application can supply a method for a window class that returns true to trigger a variation on if and when portions of the window's scrolling canvas get drawn.
Returning true declares that the window's redisplay-window method always draws the entire scrolling canvas (see page-width and page-height) as needed to keep the whole canvas up-to-date, rather than drawing only the currently-visible window interior as usual.
When true is returned, scrolling a window will not bother to draw the part of the canvas that gets scrolled into view, because it is known to be already drawn. That saves time when scrolling, though it requires drawing the whole canvas initially even though much of it may never get scrolled into view. So this is a trade-off that may be better for some kinds of windows.
When true is returned and invalidate is called on the window with no box argument, it will invalidate the entire scrolling canvas of the window rather than just the currently visible portion as it does otherwise. That will be reflected in the box argument that is passed to the window's redisplay-window method. Therefore, redrawing can be optimized in all cases by making a redisplay-window method always draw only things that intersect its box argument.
This is applicable only in CG/JS mode because every window has a backing-store memory bitmap in JavaScript for the whole scrolling canvas (except in small-canvas-mode). In Windows desktop mode, this is true only of a bitmap-pane or a bitmap-stream.
See also small-canvas-mode for a different approach that saves memory when a window has a large scrolling canvas. (It is not useful to use small-canvas-mode and draws-the-entire-scrolling-page together.)
Generic Function, cg package
Arguments: printer
Returns the value of the driver-collate-p property of the printer stream identified by the argument. If this printer stream property is turned on, it indicates that the user has requested on the print job dialog that the printed output be collated, and also that the printer driver is capable of doing the collating internally, and so the application does not need to print pages in a collated order explicitly.
Whether to collate may be specified programmatically by passing the :collate-p initarg to open-stream when creating the printer stream, or may be specified by the end user on the print job dialog that appears by default when calling open-stream to create a printer stream. The values of the driver-collate-p and user-collate-p properties will then indicate whether the application or the printer driver should handle the collating, if any.
driver-collate-p is a property of the printer class.
Generic Function, cg package
Arguments: printer
Returns the value of the driver-copies property of the printer stream identified by the argument. If this printer stream property is greater than 1, it indicates that the user has requested on the print job dialog that multiple copies be printed, and furthermore that the printer driver knows how to print the multiple copies itself, and so the application does not need to explicitly print multiple copies of whatever output it is printing.
The number of copies to print may be specified programmatically by passing the :copies initarg to open-stream when creating the printer stream, or may be specified by the end user on the print job dialog that appears by default when calling open-stream to create a printer stream. The values of the driver-copies and user-copies properties will then indicate whether the application or the printer driver should handle printing the multiple copies, if any.
driver-copies is a property of the printer class.
Generic Function, cg package
Arguments: printer
Returns the name of the driver that this printer uses. The value is usually "winspool", and is probably not of much use to applications.
Generic Function, cg package
Arguments: printer
Returns a string supplied by the printer driver to indicate the version of the printer driver software that is being used.
driver-version is a property of the printer class.
This generic function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Function, cg package
Arguments: combo-box
Drops (open like a pop-up menu) combo-box programmatically. See the description of the combo-box control.
Generic Function, cg package
Arguments: dialog-item
Returns the mouse cursor image to be used while doing a drag-and-drop whenever the mouse cursor is over dialog-item and dropping onto that dialog-item is allowed. (droppable-p methods determine where dropping is allowed.)
An application typically would not need to call this generic function, but may define methods on it to customize the mouse cursors that are used by drag-and-drop. The returned value should be either an instance of the cursor class or a mouse cursor handle.
The default method returns the mouse cursor instance which is returned by the expression (find-cursor :default-drop-cursor) (see find-cursor). This cursor shows a thick arrow pointing downward, indicating that a drop is allowed onto this dialog-item.
drag-cursor and no-drop-cursor return mouse cursors to use at other times during a drag.
Generic Function, cg package
Arguments: tab-control
Called when an allowed drop is being done to retrieve the value to be dropped. The default method for many classes returns the selected-object of the dragged control, which is generally the value.
Other built-in drop-get methods specializing on button, picture-button, check-box, and radio-button return the title of the control, since the value is not very interesting for dragging.
See the description of the tab-control class/control.
Generic Function, cg package
Arguments: dropping-outline &optional no-set-focus-p
This can be called to programmatically show the dropping pane of a dropping-outline, without the user clicking on the widget as usual to show it. It has no effect if the dropping pane is already shown. The keyboard focus will move to the dropping pane unless no-set-focus-p is true.
This function is called internally when the user clicks on the widget to show the dropping pane, so an :after method could be added for side effects, such as showing a help message.
Generic Function, cg package
Arguments: tab-control value &optional position
Called when an allowed drop takes place to tell the control over which the value was dropped to accept the value in some way. The default method sets the value of the control to be the dropped value.
Other built-in drop-put methods specializing on button, picture-button, check-box, and radio-button set the title of the control, since the value is not very interesting.
The method for an item-list also adds the new-value to the item-list's range if not there, placing it between existing items according to where the mouse cursor is located at the time of the drop.
The method for combo-box also adds the new-value to the combo-box's range if not there already.
The methods for editable-text and multi-line-editable-text coerce the new-value to a string before dropping it in.
See the description of the tab-control class/control.
Generic Function, cg package
Arguments: dialog-item
Specifies whether a call to drag-and-drop will be allowed to drop values onto the widget specified by the argument dialog-item, and from which widgets that initiated the drag. The value may be nil to never allow dropping, t to allow dropping from any other widget, or a list of the names of the widgets from which a drop is allowed.
In general, a drop is allowed if droppable-p returns true when it is called on the dropped-on widget and the dragged-from widget. The default droppable-p method returns whether this drop-sources property indicated that the drop is allowed. This property is a simpler alternative to defining widget subclasses and droppable-p methods.
Generic Function, cg package
Arguments: widget
Should return true if and only if an application allows dropping control onto itself during a drag-and-drop gesture. The default method returns nil, but an application may add droppable-onto-self methods to allow particular controls to be dropped onto themselves.
See drag-and-drop.
Generic Function, cg package
Arguments: dropped-on-widget drag-from-widget
Current behavior (starting in release 11.0). See below for behavior in earlier releases**.
This generic function should return true if and only if a drop should be allowed when drag-and-drop is called on dragged-from-widget and the user attempts to drop the dragged value onto dropped-on-widget. An application can add droppable-p methods to control when dropping is allowed, based on the widget classes.
The default droppable-p method returns whether the drop-sources property of dropped-on-widget indicates that the drop should be allowed. Specifying that property for individual widgets may be simpler than defining widget subclasses and droppable-p methods on them, and can be done in the inspector as usual when designing dialogs interactively as form windows.
Pre-11.0 behavior: Returns true if drag-from-widget is droppable on dropped-on-widget.
The default droppable-p method returns nil, so an application needs to add droppable-p methods that return true for those cases where dropping should be allowed. In the IDE, only the Inspector allows values to be dropped into it. (To initiate a drag in the IDE, hold the Alt key and then left-click and drag a value.)
Generic Function, cg package
Arguments: combo-box
This property of combo-boxes in earlier releases is no longer supported. The old description follows. combo-boxes ignore this property and always display a drop-down list when you click on them (rather than displaying the choices all of the time). This means combo-boxes behave as if this property has value t.
Here is the old description: Returns the value of the dropping property of combo-box. This property determines whether a combo-box displays as a drop-down-list or an always-visible list.
See the description of the combo-box control.
Generic Function, cg package
Arguments: text-edit-pane
This function has an effect only on the Windows platform.
Returns true or nil to indicate whether text-edit-pane (a text-edit-pane) will automatically use an English font for ASCII text and an Asian font for Asian text. The value may be set when creating the window by passing a dual-fonts-for-languages initarg to make-window, or any time later by calling (setf dual-fonts-for-languages). The default value is nil.
This function is a direct hook into the IMF_DUALFONT option of Microsoft's RichEdit control. The behavior above is simply what Microsoft documents.
See also automatic-font-changing.
Generic Function, cg package
Arguments: grid-section-any
Returns the position of grid-section within a grid-widget or the position of a grid-subsection within its parent grid-section. The value is a non-negative integer indicating a distance in pixels.
For a grid-row-section, the distance is from the top of the grid interior to the top edge of the grid-row-section. For a grid-column-section, the distance is from the left of the grid interior to the left edge of the grid-column-section.
For a grid-row, the distance is from the top of the set of rows in the grid-row-section of the row to the top edge of the row. For a grid-column, the distance is from the left edge of the set of columns in the grid-column-section of the column to the left edge of the column. Note that this value is not affected by the scrolling of the grid-section, since the value is relative to the scrolling contents of the section rather than to their position in the widget window.
Compatibility note: Through version 6.0, the value returned for a grid-row or grid-column was equal to the value described here added to the edge-position of the parent grid-section. This was not an intuitive value, and so the function has been changed to match the current documentation.
Generic Function, cg package
Arguments: grid-column
Returns the value of the edit-end-trigger of the argument. The possible values are :enter and :enter-or-arrow-keys. They mean, respectively, that when editing in grid-column, pressing the Enter key ends editing or pressing the Enter key or an arrow key ends editing.
edit-start-trigger is a property of the editable-text-column-mixin and combo-box-column-mixin classes. (For combo-box-column-mixin, this property and edit-start-trigger have no effect unless the typable property is turned on.)
Function, cg package
Arguments: window &key string box font background-color foreground-color close justification draw-border single-line help-string lisp-form
Places a temporary edit-pane on window at box to allow the user to edit string. This is typically done in place, which means that box is positioned directly over a string that is already displayed as part of a larger interface.
The arguments are:
window is the window on which the type-in will take place.
string is the initial string to edit. Defaults to the null string.
box is the subregion of the window where the type-in will take place. Defaults to the whole interior of the window.
font is the font to use for editing the string. Defaults to the current font of the window.
background-color is an rgb color for the background of the text. Defaults to the current background-color of the window.
foreground-color is an rgb color for the foreground of the text. Defaults to the current foreground-color of the window.
close is a boolean which if true, then the small edit pane is closed after the type-in is complete. Otherwise it is not closed and is reused the next time an edit-in-place is done on window. The latter may make the edit-in-place begin a bit faster, but results in more leftover edit-in-place panes hanging around. Defaults to t.
justification is either :left, :center, or :right to indicate the horizontal justification of the edited text. Defaults to :left.
draw-border is a boolean which if true, then a border is drawn around the text being edited during the type-in. The value may be either nil for no border, t for a default static border, or any of the border styles that may be passed to make-window. Defaults to nil.
single-line is a boolean which if true then the edited text will always be a single line of text, and otherwise will wrap to multiple lines as needed in order to fit within the width of box. Defaults to nil.
help-string is a string to display in the status bar at the beginning of the type-in.
lisp-form is a boolean which if true causes the edit-pane to be a lisp-edit-pane.
Generic Function, cg package
Arguments: grid-column
Returns the value of the edit-start-trigger of grid-column. The possible values are :click, :get-focus, and :begin-typing. When you can edit by typing to a cell in grid-column, this property indicates what action by the user indicates that editing should begin.
edit-start-trigger is a property of the editable-text-column-mixin and combo-box-column-mixin classes. (For combo-box-column-mixin, this property and edit-end-trigger have no effect unless the typable property is turned on.)
Generic Function, cg package
Arguments: outline
Returns the value of the editable-in-place property of the argument. This property determines whether the user may type a new value directly into any item of this outline. If true, then an edit-in-place operation is begun whenever the user clicks on an outline item that is already selected (as in MS Windows Explorer). After the user types in a string and presses ENTER, the outline-item's value is set to what the user has typed. If the original outline-item value was a string, then the new string is used directly; otherwise a read-from-string is performed on the typed-in string to produce the Lisp object that is used as the new outline-item value.
Note that if the outline-item values are high-level objects, as is often the case, this property has limited usefulness. It is difficult (and for users rather than programmers, likely impossible) to type in a high-level object (the printed representation generally is not correct).
editable-in-place is a property of the outline class.
Generic Function, cg package
Arguments: class-grid-or-object-editor
Returns the name of a class whose instances can be displayed and edited by the specified class-grid widget or object-editor dialog. The value can be set when creating either of those interface objects by passing an edited-class initarg, or any time later by calling (setf edited-class).
The class would typically be an AllegroCache persistent class, but may be any class.
class-grid-or-object-editor should be either a class-grid or an object-editor.
The edited-slots property should reference slots that exist on this class. The value of a class-grid, or the edited-instances of an object-editor, should be instances of this class.
Generic Function, cg package
Arguments: object-editor
Returns a list of the particular instances that an object-editor dialog is editing, or nil if the object-editor is editing all instances of a persistent class. The value may be set with the edited-instances initarg at creation time, or any time later by calling (setf edited-instances). The default value is nil. If this property is never set, then the dialog will attempt to edit all instances of its edited-class, though this requires that the class be a persistent (AllegroCache) class so that all instances can be found.
At this time, editing a huge number of instances may be unwieldy because an object-editor always sorts the instances (typically according to the primary-name-slot of the class if any), which entails loading every instance from a database (if the instances are coming from a database). This is done to facilitate browsing the instances in an intuitive order, and for the object-editor-select facility to be able to present many instances as a series of alphabetized pop-up menus. And the object-editor-search facility needs to load every instance in order to search one or more of its slots. Options may be added in the future to facilitate handling large databases better.
For the related class-grid widget, the value property is used instead of an edited-instances property to store the list of instances, and a value of nil will display no instances rather than all of them.
Generic Function, cg package
Arguments: dialog-item
Returns the name of the slot that a widget on an object-editor edits. This symbol is exported only because it is included in code that is generated for an object-editor form. An application should use the edited-slots property of the object-editor instead of this accessor.
Generic Function, cg package
Arguments: class-grid-or-object-editor
Returns the edited-slots property value of an object-editor dialog or class-grid widget. The value may be set when creating either of those interface objects by passing the edited-slots initarg, or anytime later by calling (setf edited-slots).
An edited-slots value is a high-level specification that tells an object-editor or class-grid which slots of its edited-class it should edit, and how it should edit each of those slots. When the edited-slots property is set, an object-editor will create or update its widgets as needed for editing those slots as specified, or a class-grid will create or update its grid columns.
When creating an object-editor dialog as a form window in an IDE project, or when creating a class-grid on a form, the edited-slots value can be specified interactively using the IDE's Class Interface Editor. Otherwise the expression must be specified programmatically using the options documented here. For an extended example of specifying an edited-slots expression programmatically, see Creating an Object-Editor Dialog or Class-Grid Programmatically.
Here is small sample edited-slots value:
((last-name
:edited-type (:variable-char)
:width 120)
(date-of-birth
:edited-type (:date :yyyy/mm/dd))
(favorite-color
:edited-type (:single-choice (:red :green :blue :yellow))
:on-print capitalize-object
:label "Fave Color")
(best-friend
:edited-type (:class-instance patient)
:width 140)
((best-friend date-of-birth)
:label "Best Friend's Birth Date"
:edited-type (:date :yyyy/mm/dd)))An edited-slots value is a list where each element of the list describes how to edit a particular slot. We'll call these elements slot entries here. A slot entry is a list where the first element is a slot reference, and the rest of the list is an options plist.
A slot reference is either a slot name or a list of slot names. When it is a slot name, it should be the name of a slot of the edited-class of the object-editor or class-grid. In that case, the widget or grid column that is created will directly access that slot of the displayed instances. When it is a list of slot names, then the widget or grid column will indirectly access a slot of some other object; see Editing Slots Indirectly below.
An options plist consists of alternating option keywords and option values that determine how the generated user interface will edit a particular slot. A special option is the :edited-type option that determines the type of widget that will be used and such things as what choices it might offer. Other options are generally geared toward the look and feel.
An :edited-type value is a list where the first element is a keyword that indicates which basic type of editing to use, such as :variable-char or :class-instance. The rest of the list contains zero, one, or two parameters, depending on the basic type. Here is a list of all of the basic editing types, their meanings, and what else should be in the list for each type.
:static-text - The value is displayed as a single line of text of any length, and the user cannot modify the value. There are no parameters. An object-editor will use a static-text widget, and a class-grid will use a class-grid-static-text-column with its single-line property set to true. If the slot value is not a string, then princ-to-string is used to produce a string.
:static-text-multi-line - the value is displayed as multiple lines of text of any length, and the user cannot modify the value. There are no parameters. An object-editor will use a scrolling-static-text widget, and a class-grid will use a class-grid-static-text-column with its single-line property set to nil. If the slot value is not a string, then princ-to-string is used to produce a string.
:variable-char - the value is displayed as a single line of text of any length, and the user can modify the value. There are no parameters. An object-editor will use an editable-text widget, and a class-grid will use a class-grid-editable-text-column.
:variable-char-multi-line - the value is displayed as multiple lines of text of any length, and the user can modify the value. There are no parameters. An object-editor will use a multi-line-editable-text widget, and a class-grid will use a class-grid-editable-text-column.
:fixed-char - the value is displayed as a single line of text of a specific length, and the user can modify the value. There is one parameter, which is the length of the string. An object-editor will use an editable-text widget with a template-string, and a class-grid will use a class-grid-editable-text-column with a template-string. The :horizontal-justification option defaults to :left.
:fixed-numeric - the value is displayed as a single line of text of a specific length, and the user can modify the value. The user can enter only numerals, or a plus or minus character if the :template-allows-sign option is true and there are no non-space characters to the left of the current position. There are two parameters, the first being the number of digits before the decimal point, and the second being the number of digits after the decimal point. An object-editor will use an editable-text widget with a template-string, and a class-grid will use a class-grid-numeric-editable-text-column with a template-string. The :horizontal-justification option defaults to :right.
:date - the value is displayed as a single line of text of a specific length, and the user can modify the value. There is one parameter, which is a keyword indicating the format of the date string; possible values currently are :yyyy/mm/dd, :mm/dd/yyyy, :mm/dd/yy, :dd/mm/yyyy, and :dd/mm/yy. The user can enter only numerals. An object-editor will use an editable-text widget with a template-string, and a class-grid will use a class-grid-editable-text-column with a template-string. The :horizontal-justification option defaults to :left.
:boolean - the value is displayed as nil or true (which is anything other than nil), and the user can toggle the value between nil and t. There are no parameters. An object-editor will use a check-box widget, and a class-grid will use a class-grid-check-box-column.
:single-choice - the value is displayed as a single line of text, with a dropping list of choices from which the user can select a single choice. There is a single parameter, which is the list of choices. An object-editor will use a combo-box widget, and a class-grid will use a class-grid-combo-box-column.
:multiple-choice - the value is displayed as selected items in a list of all choices. There is a single parameter, which is the list of choices. An object-editor will use a multi-item-list with the simple-click-toggle property set to true. This option is not implemented in a class-grid.
:pixmap - the value is displayed as a pixmap that represents an associated slot value. The user can modify the value by clicking the widget or grid cell, or by pressing the spacebar when the widget or grid cell has the keyboard focus. This action changes the pixmap to the next choice (cycling through all choices repeatedly as needed) and sets up the associated user value to be written to the slot (if confirmed, as usual). There may be either one or two parameters. The first parameter is an association list that maps arbitrary slot values to pixmaps. The first element of each alist entry is an arbitrary slot value, and the second is the name of a pixmap that has been cached by calling cache-pixmap. If the current slot value is not in the alist, then no pixmap is drawn (the widget or grid cell will be blank). A pixmap value may be nil to not draw a pixmap but still allow the user to set the slot to the associated value by cycling to it as usual with the mouse or spacebar. The (optional) second parameter may be nil or true, indicating whether the pixmap should stretch to fill the available space in the widget or grid cell; it defaults to nil to draw the pixmap at its normal size.
:static-pixmap - like :pixmap, except that the user cannot modify the value interactively. Clicking the pixmap or pressing the spacebar will have no effect.
:class-instance - the value is expected to be a class instance, and is displayed as a single line of text, with a dropping list of choices from which the user can select a single choice. There is one parameter, which is the name of the class of which the slot holds an instance. A separate :edited-instances option may be a list of instances to offer as choices. The primary-name-slot and/or secondary-name-slot of the class (if any) will be used to find the string to display for each instance; otherwise the class's print-object method will be used. An object-editor will use a combo-box widget, and a class-grid will use a class-grid-combo-box-column.
:static-class-instance - the value is expected to be a class instance, and is displayed as a single line of text, and the user cannot modify the value. There is one parameter, which is the name of the class of which the slot holds an instance. The primary-name-slot and/or secondary-name-slot of the class (if any) will be used to find the string to display for each instance; otherwise the class's print-object method will be used. An object-editor will use a static-text widget, and a class-grid will use a class-grid-static-text-column.
:table-of-class-instances - the value is expected to be a list of class instances of a single class, and is displayed as a table. There is one parameter, which is the name of the class of the instances. A nested :edited-slots option should be passed to specify the columns of the table. An object-editor will use a slot-editing-class-grid. This option is not implemented in a class-grid. The user can edit the instances in the class-grid as with any class-grid, so static types should be used for the columns if you don't want the end user to be able to edit the instances indirectly in this table.
:lisp-type - the value is displayed as a single line of text that is printed via princ-to-string. The user can modify the text, which is then read with the Lisp reader to return a Lisp object to return to the slot. There is one parameter, which is the Lisp type of the values; it may be any Lisp type, though only some types of Lisp values may be saved in an AllegroCache database. An object-editor uses a lisp-text widget, and a class-grid uses a class-grid-lisp-text-column.
Here are the options other than the special :edited-type option documented just above.
:label - a string to display beside a widget in an object-editor or in a column header of a class-grid. If nil or unspecified, defaults to the name of the edited slot with dashes converted to spaces and then each word capitalized.
:width - the width of the widget or grid-column, measured in pixels. If nil or unspecified, a default value will be used. For the fixed-length types, a default width is computed that fits the number of characters in the template-string. For the pixmap types, the default is 32. For the :table-of-class-instances type, the default is the entire interior width of the object-editor, minus the outer margins and any room taken up by the table's helper buttons. For all other types, the default is the layout-widget-width of the layout-spacing of an object-editor, or the default-column-width of a class-grid.
:height - the height of the widget, measured in pixels. Not applicable to class-grid, where the body-row-height of the class-grid is always used. If nil or unspecified, a default value will be used. For a multi-line widget, the default is the layout-multi-line-widget-height of the layout-spacing of the object-editor. For a single-line widget, the default is the layout-single-line-widget-height of the layout-spacing of the object-editor if that is non-nil, and otherwise a height that fits the widget's font. For a type that is implemented as a combo-box, the standard combo-box height will be used (with a dropping list that's 200 pixels tall). For the pixmap types, the default is 32. For the :table-of-class-instances-type, the default is the layout-table-height of the layout-spacing of the object-editor.
:width-in-chars - the width of the widget or grid-column, measured in "m" characters. When true, this option takes precedence over the :width option.
:font - the font to use in the widget or grid-column. If nil or unspecified, then a default font is used according to the :fixed-width-font option.
:fixed-width-font - used only when the :font option is nil or unspecified. A boolean value indicating whether the default font that is used has fixed-width characters. If this option is specified as true, then the global Common Graphics fixed-font is used. If this option is specified as nil, then the global Common Graphics proportional-font is used. If this option is not specified, then fixed-font is used for the :fixed-char, :fixed-numeric, and :date types and otherwise proportional-font is used.
:help-string - a string to display when the mouse cursor is over the widget. This string will be displayed in the status-bar of the nearest ancestor window that has a status-bar, if any. If nil or unspecified, then no string is displayed.
:on-print - a function that converts a user value into a string to display. Its single argument should be the user value, and it should return the string to display. If nil or unspecified, this effectively defaults to princ-to-string for values that are not strings already.
:horizontal-justification - one of the values :left, :center, or :right. If unspecified, defaults to :right for the :fixed-numeric type and otherwise to :left. Applicable to the types :static-text, :scrolling-static-text, :variable-char, :variable-char-multi-line, :fixed-char, :fixed-numeric, :date, :static-class-instance, and :lisp-type.
:vertical-justification - one of the values :top, :center, or :bottom. If unspecified, defaults to :center. Applicable to all types in a class-grid, for positioning within a grid cell. Not applicable to object-editor.
:resizable: a boolean value indicating whether the user can change the width of the class-grid column by dragging the right edge of its header cell. Not applicable to object-editor. If unspecified, the default is t.
:proportional: a boolean value indicating whether the class-grid column's width will be adjusted proportionally when the width of the class-grid itself changes. Not applicable to object-editor. If unspecified, the default is nil.
:sortable - a boolean value indicating whether the user can sort a class-grid by the grid column for this slot. Not applicable to object-editor. If unspecified, the default is nil.
:edited-instances - a list of instances that are offered as choices for the :class-instance type. When unspecified, all class instances will be displayed if the class is persistent, and otherwise it is an error (because all instances cannot be found). This option is not allowed on a form window in a project, because the instances cannot be saved in the generated code to create the running window.
:edited-slots - applicable only to the :table-of-class-instances type, which is allowed only on an object-editor. Specifies a nested edited-slots specification for the columns of a class-grid widget that's on an object-editor dialog.
:template-allows-sign - applicable only to the :fixed-numeric type. A boolean value indicating whether the user is allowed to type a plus or minus character to the left of all non-whitespace characters. If unspecified, the default is nil.
:edit-start-trigger - one of the values :click, :get-focus, or :begin-typing, determining the user action that will begin text editing in a grid cell. See edit-start-trigger. Applicable only to class-grid, and only for the types :fixed-numeric, :fixed-char, :date, :variable-char, and :variable-char-multi-line. If unspecified, the default is :click. See edit-start-trigger.
:edit-end-trigger - one of the values :enter or :enter-or-arrow-keys, determining the user action that will end text editing in a grid cell. See edit-end-trigger. Applicable only to class-grid, and only for the types :fixed-numeric, :fixed-char, :date, :variable-char, and :variable-char-multi-line. If unspecified, the default is :enter. See edit-end-trigger.
When a slot reference is a list of slot names, the associated widget or grid column will indirectly edit a slot of some object other than the one being displayed by the object-editor or class-grid. It does this by taking the first slot-name in the list and reading the value of that slot of the displayed instance. If there are further slot names in the list, then the value that was read is expected to be a first-class object (a class instance), and the next slot in the list is read from that object. That continues until the last slot is read.
For example, if an object-editor is editing a patient, and the slot reference for one of its widgets is (hospital ceo phone-number), then the widget will read what should be a hospital object from the hospital slot of the patient that the object-editor is currently displaying, then read a CEO object from the ceo slot of that hospital object, and then read a value from the phone-number slot of that CEO object. This will hopefully be the phone number of the CEO of the hospital of the patient. If the user edits the value of the widget and saves it, then this would change the CEO's phone number even though the dialog is editing a patient. For that reason, it's probably usually appropriate to use static (non-editable) widgets for indirect slot references.
Generic Function, cg package
Arguments: dialog-item
Returns a description of the type of value that is held in a slot that a widget on an object-editor edits. This symbol is exported only because it is included in code that is generated for an object-editor form. An application should use the edited-slots property of the object-editor instead of this accessor.
Function, cg package
Arguments: object &key base-color scratch-rgb
Returns the color returned by background-color for object if that function returns a color (rather than t or nil).
The value will be an RGB color (as returned by make-rgb). See hls-to-rgb and rgb-to-hls.
If the scratch-rgb argument is specified, it should be a RGB object which will be modified to be the effective background color. This avoids consing a new RGB object.
The base-color argument is used internally and should not be specified by applications.
If background-color returns nil, effective-background-color returns the color returned by default-background-color for object. (As of 5.0, background-color returns nil when no background color has been explicitly assigned to an object.)
If background-color returns t for a control, indicating that the control's background color should be the same as its parent window's background color, then the effective-background-color of the parent window is returned.
Generic Function, cg package
Arguments: section
Returns the color that will be used to draw the border along the right side of a grid-column or grid-column-section or along the bottom side of a grid-row or grid-row-section. An application may either call or override this generic function, though it typically should not be necessary to do either, since border colors are usually specified with the border-color and/or default-cell-border-color properties, and effective-border-color is called internally whenever a grid border line is drawn.
The default method for grid-subsection (for a grid-row or a grid-column) will return the border-color property of the subsection if non-nil. Otherwise it will return the default-cell-border-color of the grid-section that contains the subsection, if non-nil, or else the default-cell-border-color property of the whole grid-widget, if non-nil. If none of these properties have been specified, then the color returned by system-disabled-color is returned (since the return value must be an actual color).
The default method for grid-section (for a grid-row-section or a grid-column-section) will return the section's border-color property if non-nil, or else the default-cell-border-color property of the whole grid-widget, if non-nil, or finally the color returned by system-edge-shadow-color.
Generic Function, cg package
Arguments: grid-section-or-subsection
Returns the width in pixels that will be used to draw the border along the right side of a grid-column or grid-column-section or along the bottom side of a grid-row or grid-row-section. An application may either call or override this generic function, though it typically should not be necessary to do either, since border widths are usually specified with the border-width and/or default-cell-border-width properties, and effective-border-width is called internally whenever a grid border line is drawn.
The default method for grid-subsection (for a grid-row or a grid-column) will return the border-width property of the subsection if non-nil. Otherwise it will return the default-cell-border-width of the grid-section that contains the subsection, if non-nil, or else the default-cell-border-width property of the whole grid-widget, if non-nil. If none of these properties have been specified, then 1 is returned (since the return value must be an actual width).
The default method for grid-section (for a grid-row-section or a grid-column-section) will return the section's border-width property if non-nil, or else the default-cell-border-width property of the whole grid-widget, if non-nil, or finally 2.
Function, cg package
Arguments: object &key base-color scratch-rgb
Returns the color returned by foreground-color for object if that function returns a color (rather than nil). The value will be an RGB color, as returned by make-rgb.
If the scratch-rgb argument is specified, it should be a RGB object which will be modified to be the effective foreground color. This avoids consing a new RGB object.
The base-color argument is used internally and should not be specified by applications.
If foreground-color returns nil, effective-foreground-color returns the color returned by default-foreground-color for object. (As of 5.0, foreground-color returns nil when no foreground color has been explicitly assigned to an object.)
Generic Function, cg package
Arguments: value-axis
Returns a list of the bottom and top (or left and right) of the current effective range of the specified value-axis of a chart-widget. This may be needed when not explicitly setting the range-bottom and range-top properties, to find the range that the widget automatically chooses as round values that surround all of the current data values.
Function, cg package
Arguments: center smaj-axis smin-axis smaj-axis-angle start-angle length-angle
This function may be used to find the x and y coordinates of the endpoints of an elliptical arc that was drawn (or might be drawn). This may be needed for example when drawing a pie chart where you need to draw an elliptical arc and then draw straight lines from its endpoints to the arc center.
The arguments should be the same as those passed to the functions draw-ellipse-arc, draw-ellipse-sector, and fill-ellipse-sector (excluding the initial stream argument to those functions).
ellipse-start-and-end returns four values:
the x coordinate of the starting point
the y coordinate of the starting point
the x coordinate of the ending point
the y coordinate of the ending point
This function may also be used along with draw-circle-arc, draw-circle-sector, and fill-circle-sector by passing the radius for both smaj-axis and smin-axis, and passing 0 for smaj-axis-angle.
Other calculations similar to the one performed by this function could be done by calling the Common Lisp trigonometry functions such as sin and sin. But note that the angle arguments to those functions are in radians, while angle arguments to Common Graphics functions are in degrees. To convert from degrees to radians, multiply degrees by the value returned by (/ (* 2.0 pi) 360.0). (That value is a double-float. Coerce it to a single-float if you wish to work with single-floats.)
Generic Function, cg package
Arguments: grid-section
The color for drawing any part of a grid-section that is not covered by rows or columns.
The value must be an RGB color (as returned by make-rgb) or nil, which means default to the system-dialog-background-color.
empty-color is a property of the grid-section, grid-column-section, and grid-row-section classes.
Generic Function, cg package
Arguments: window enable-p
Allows or inhibits the forwarding of events to window and its descendants. This is how Allegro CL disables other windows when a modal dialog is being displayed. If enable-p is nil, then events are disabled. If enable-p is true, events are re-enabled.
See also with-events-disabled and events-enabled.
Generic Function, cg package
Arguments: stream &key (draw t) (fill nil)
Stops collecting line-drawing function calls on stream into a "path", and then draws and/or fills the entire path as a unit. stream should be a cg-stream.
The path is drawn as specified in the intervening line-drawing function calls if and only if draw is true. The path is filled if and only if fill is true. Either draw or fill (or both) should be true, as otherwise any line-drawing done between the call to begin-drawing-path and the call to end-drawing-path is lost.
A path is useful for filling a collection of lines and curves as a unit.
To ensure that end-drawing-path is always called for each call to begin-drawing-path, it is convenient to use with-drawing-path instead of separate calls to begin-drawing-path and end-drawing-path.
See also: line-end, with-line-end, line-join, with-line-join, begin-drawing-path, and with-drawing-path.
Generic Function, cg package
Arguments: item-axis
Returns the value of the end-margin property of a item-axis. The value may be set at creation time by passing the end-margin initarg, or any time later by calling (setf end-margin).
The distance between each end of an item-axis in a chart-widget and the first chart item at that end of the axis (when the chart is scrolled all the way to that end of the item-axis). The distance is measured in pixels. The value should be a non-negative integer, or else nil to use a default distance. The default value is nil.
If the chart-view property of the chart-widget is :line, then the default distance is zero. If the chart-view is :bar, then the default distance is the bar-spacing of the bar-chart-view. The default distance is typically appropriate, though an explicit one could be supplied for aesthetic reasons.
See chart-widget and also .
Generic Function, cg package
Arguments: printer
Returns the value of the end-page property of printer. This property defines the last page of the range of pages to be printed, as requested by the user on the print job dialog. The application should interpret the start-page and end-page properties of the printer stream and print only the appropriate part of the output.
end-page is a property of the printer class.
This generic function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream using the :end-page initarg. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Generic Function, cg package
Arguments: split-bar
Returns the end1-position property of a split-bar widget. The value may be set at creation time by passing the :end1-position initarg to make-instance, or any time later by call (setf end1-position).
This property can be used to prevent the left end of a horizontal split-bar, or the top end of a vertical split-bar, from extending all the way to the interior edge of the parent window.
If nil (the default value), the split-bar will extend to the interior left or top edge of the parent window. Otherwise the value should be a non-negative integer indicating the distance from the left or top edge of the window at which the split-bar should end. The value may be set at creation time by passing the :end1-position initarg to make-instance, or any time later by call (setf end1-position).
The equivalent property for the right/bottom end is end2-position.
Generic Function, cg package
Arguments: split-bar
Returns the end2-position property of a split-bar widget. The value may be set at creation time by passing the :end2-position initarg to make-instance, or any time later by call (setf end2-position).
This property can be used to prevent the right end of a horizontal split-bar, or the bottom end of a vertical split-bar, from extending all the way to the interior edge of the parent window.
If nil (the default value), the split-bar will extend to the interior right or bottom edge of the parent window. Otherwise the value should be a non-negative integer indicating the distance from the left or top edge of the window at which the split-bar should end. The value may be set at creation time by passing the :end2-position initarg to make-instance, or any time later by call (setf end2-position).
The equivalent property for the left/top end is end1-position.
Function, cg package
Arguments: &key format
This function converts any objects that were placed onto the Windows clipboard by other applications into Lisp objects on the Lisp clipboard stack. This is not done automatically when the Windows clipboard changes, in order to avoid needless consing, but is done automatically as needed when pasting the values into the IDE or standalone Lisp application. If an application needs to look at these values without pasting them, it may find it useful to call this function and then retrieve the value of *clipboard* which will then contain the converted values. Alternately, clipboard-object could be called to retrieve the values directly without affecting the Lisp clipboard stack at all.
The format argument may be either nil to convert Windows clipboard values that are in any of the formats currently implemented in Common Graphics, or one of the symbols (:text :rich-text :pixmap) to convert only one format.
See cg-clipboard.html.
Generic Function, cg package
Arguments: stream box
Erases (i.e. replaces with the background color or texture) box from stream. box must be a box object, such as created by make-box. stream should be a graphical-stream.
Contrast with draw-box, which draws a box on a stream.
To use individual coordinates rather than creating position objects, see erase-box-x-y.
Generic Function, cg package
Arguments: stream left top right bottom
Erases a rectangle on stream from an upper-left position at (left, top) to a lower-right position at (right, bottom). (Erasing means drawing in the stream's background-color.) stream should be a graphical-stream. The other arguments should be integers. To use a box object rather than individaul coordinates, see draw-box.
Generic Function, cg package
Arguments: stream offset
Erases (i.e. replaces with the background color or texture) from stream the line from the current position (see current-position) to the position
(position+ (current-position stream) offset)offset must be a position object (see make-position). stream should be a graphical-stream.
Contrast with draw-by which draws the line on stream.
position+ adds two positions.
To use individual coordinates rather than creating position objects, see erase-by-x-y.
Generic Function, cg package
Arguments: stream x y
Erases a line from the current position in stream to a position that is x pixels to the right of the current position and y pixels downward from the current position. (Erasing means drawing in the stream's background-color.) stream should be a graphical-stream. x and y should be integers. To use a position object rather than individual coordinates, see erase-by.
The current position may be set by calling move-to-x-y.
Generic Function, cg package
Arguments: stream center radius
Erases from stream (i.e. replaces with the background color or texture) the circle defined by center and radius. center must be a position object, as created with make-position. stream should be a cg-stream.
Contrast with draw-circle which draws the circle on stream.
Generic Function, cg package
Arguments: stream center radius start-angle length-angle
Erases from stream (i.e. replaces with the background color or texture) the specified circle-arc, which is the arc extending length-angle from start-angle on the circle defined by center and radius.
center should be a position (see make-position). stream should be a cg-stream.
See also draw-circle-arc.
Generic Function, cg package
Arguments: stream center radius start-angle length-angle
Erases from stream (i.e. replaces with the background color or texture) the specified circle-sector. A circle-sector is an arc with length length-angle starting at start-angle on the circle defined by radius and center, along with the radii connecting the vertices of the arc with the center (i.e. a shape like a piece of pie).
center must be a position object, as created with make-position. stream should be a cg-stream.
Contrast with draw-circle-sector which draws the circle-sector on stream.
Generic Function, cg package
Arguments: stream box
Erases (i.e. replaces with the background color or texture) the specified filled box from stream. box must be a box object, such as created by make-box. stream should be a graphical-stream.
Contrast with fill-box, which draws a filled box on stream.
To use individual coordinates rather than creating position objects, see erase-contents-box-x-y.
Generic Function, cg package
Arguments: stream left top right bottom
Unfills a rectangular area on stream from an upper-left position at (left, top) to a lower-right position a (right, bottom). (Unfills means to fill with the stream's background-color.) stream should be a graphical-stream. The other arguments should be integers. To use a box object rather than individaul coordinates, see erase-contents-box.
The filled area will include the pixels where the x coordinate is equal to left and those where the y coordinate is equal to top, but not the pixels where the x coordinate is equal to right or those where the y coordinate is equal to bottom.
Generic Function, cg package
Arguments: stream center radius
Erases (i.e. replaces with the background color or texture) the filled circle defined by center and radius from stream. center must be a position (see make-position). stream should be a cg-stream.
Contrast with fill-circle which draws the filled circle on stream.
Generic Function, cg package
Arguments: stream center radius start-angle length-angle
Erases (i.e. replaces with the background color or texture) the specified filled circle-sector from stream. A circle-sector is an arc with length length-angle starting at start-angle on the circle defined by radius and center, along with the radii connecting the vertices of the arc with the center (i.e. a shape like a piece of pie). Contrast with fill-circle-sector which draws the filled circle-sector on stream.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle
Erases (i.e. replaces with the background color or texture) the specified filled ellipse from stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise.
center should be a position (see make-position). stream should be a cg-stream.
See fill-ellipse.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle start-angle length-angle
Erases (i.e. replaces with the background color or texture) the specified filled ellipse-sector from stream. An ellipse-sector is an ellipse-arc with the endpoints of the arc connected to the center of the ellipse, like a piece of an elliptical pie.
The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise.
center should be a position (see make-position). stream should be a cg-stream.
Contrast with fill-ellipse-sector which draws the filled ellipse-sector on stream.
Generic Function, cg package
Arguments: stream vertices
Erases (i.e. replaces with the background color or texture) the specified filled polygon from stream. A polygon is specified by vertices, which should be a sequence (list or vector) of positions (see make-position). A line is drawn connecting the first vertex with the final vertex.
stream should be a cg-stream.
Contrast with fill-polygon which draws the filled polygon on stream.
Generic Function, cg package
Arguments: stream top-left width height corner-width corner-height
Erases from stream (i.e. replaces with the background color or texture) the rounded box specified by the arguments.
stream should be a cg-stream.
Contrast with fill-rounded-box, which draws a filled rounded box on a stream. A rounded box is defined on that page.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle*
Erases ellipse from stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise.
center should be a position (see make-position). stream should be a cg-stream.
Contrast with draw-ellipse, which draws the ellipse on stream.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle start-angle length-angle*
Erases an ellipse arc from stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise. The portion of the ellipse drawn is the arc starting at start-angle (0 is the x axis when the center is the origin) through the length-angle.
center should be a position (see make-position). stream should be a cg-stream.
Contrast with draw-ellipse-arc, which draws the ellipse on stream.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle start-angle length-angle*
Erases an ellipse sector from stream. An ellipse-sector is an ellipse-arc with the endpoints of the arc connected to the center of the ellipse, like a piece of an elliptical pie.
The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise.
center should be a position (see make-position). stream should be a cg-stream.
Contrast with draw-ellipse-sector, which draws the ellipse sector on stream.
Generic Function, cg package
Arguments: stream from to
Erases from stream the line from position from to position to. from and to must be position objects, as created by make-position. stream should be a cg-stream.
Contrast with draw-line, which draws the line on stream.
To use individual coordinates rather than creating position objects, see erase-line-x-y.
Generic Function, cg package
Arguments: stream x1 y1 x2 y2
Erases a line on stream from (x1, y1) to (x2, y2). (Erasing means drawing in the stream's background-color.) stream should be a graphical-stream. The other arguments should be integers. To use position objects rather than individual coordinates, see erase-line.
Generic Function, cg package
Arguments: stream vertices
Erases (i.e. replaces with the background color or texture) the specified polygon from stream. A polygon is specified by vertices, which should be a sequence (list or vector) of positions (see make-position). A line is drawn connecting the first vertex with the final vertex. stream should be a cg-stream.
Contrast with draw-polygon which draws the polygon on stream.
Generic Function, cg package
Arguments: stream vertices
Erases (i.e. replaces with the background color or texture) the specified polyline from stream. A polyline is specified by vertices, which should be a sequence (list or vector) of positions (see make-position). Lines connect each vertex with the next vertex but (in contrast to a polygon) no line connects the last vertex to the first vertex.
stream should be a cg-stream.
Contrast with draw-polyline which draws the polyline on stream.
Generic Function, cg package
Arguments: stream top-left width height corner-width corner-height
Erases the rounded-box specified by the arguments from stream.
stream should be a cg-stream.
See also draw-rounded-box, where a rounded box is defined.
Generic Function, cg package
Arguments: stream to
Erases (i.e. replaces with the background color or texture) from stream the line from the current position (as returned by current-position applied to stream) to the to position. to must be a position object (see make-position). stream should be a graphical-stream.
Contrast with draw-to which draws the line on stream.
To use individual coordinates rather than creating position objects, see erase-to-x-y.
Generic Function, cg package
Arguments: stream x y
Erases a line from the current position in stream to the position at (x, y). (Erasing means drawing in the stream's background-color.) stream should be a graphical-stream. x and y should be integers. To use a position object rather than individual coordinates, see erase-to.
The current position may be set by calling move-to-x-y.
Function, cg package
Arguments:
Returns a pre-defined icon to indicate that an error has occurred. In CG/JS mode this is actually a pixmap, which can be used as an icon in that mode. In Windows desktop mode it is the icon that is the value of the error-icon variable.
Generic Function, cg package
Arguments: menu menu-item window-or-screen
Evaluates the value of the menu-item selected by the user. eval-menu-item is defined as:
(defun eval-menu-item (menu menu-item window-or-screen)
(eval (value menu-item)))Generic Function, cg package
Arguments: stream event-number button-state data
In general, methods should not be defined for this generic function. event is called, but it simply dispatches to the appropriate new function named for the actual event (such as mouse-right-down and mouse-moved). Instead of specializing event, you should specialize the new generic function named after the event.
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: comtab events
Returns the function in comtab that corresponds to events.
For example, this expression:
(event-function (cg-emacs-comtab) (list control-key #\f))returns the symbol forward-character.
See also set-event-function.
Generic Function, cg package
Arguments: object
Returns the subset of properties of object that specify functions to be run when various events are received by object. For example, on-click is an event-handler property because its value (if true) is a function that is to be run when the user clicks the object. Event-handler properties are displayed on the Events tab of the inspector, separate from the rest of the properties on the Properties tab. The items in the returned list are property objects and are suitable as arguments to initarg.
object can be any object. nil is returned if there are no event handlers associated with object.
Function, cg package
Arguments: &key window exit-test
Enters a loop that processes all messages that are sent to any windows that are created in the thread that is calling event-loop. When an application creates a new thread that will create windows, the preset-function that is passed to process-run-function should call event-loop before it exits, both to cause that thread's messages to be handled and also to prevent the thread from exiting until it should. The arguments determine when event-loop will return, which then allows the thread to exit.
window may be nil or a window. If a window, then event-loop will check that the window is still open after processing each message, and return when the window has been closed. Typically a "main window" for the thread is passed to event-loop.
exit-test may be nil or a function name or function object. If non-nil, then event-loop will call the exit-test function once after it has processed each message, and return if the function returns true. For efficient event-handling, an exit-test if used should execute quickly. The function should take one argument, which is the value of the window argument to event-loop. An exit-test may be used along with a null window argument (in which case the argument to the exit-test function will be nil), but it is probably most often useful to pass a main-window as well when an exit-test is used.
Note: It is not necessary to call event-loop when using the project system to create an application with a single windowing thread, because it is called automatically for the thread created by the Run | Run Project command in the IDE and by the corresponding initial thread of the generated standalone application (as long as the project's ide:on-initialization function returns a window). It is also not necessary to call event-loop when creating windows by evaluating forms in IDE listeners or editors, since the threads used for evaluation by these IDE windows are already in event-handling loops.
event-loop basically calls process-single-event in a loop until an exit requirement is met. So if event-loop does not meet an application's needs, it may work to use a custom loop that calls process-single-event itself. But event-loop performs some additional internal management and is recommended over custom process-single-event loops. In particular, event-loop ensures that multiple threads that call it will all exit cleanly when Lisp exits; otherwise multiple windowing threads may hang on exit unless the :no-unwind argument is passed to excl:exit. In a standalone application that does its own event handling (rather than returning a window from its ide:on-initialization function), calling event-loop also ensures that the Enable Debugging of Runtime Errors option behaves as documented (see the Build tab of the Project Manager).
See also About using multiple windowing threads in a Common Graphics application in cgide.html. And see inside-event-loop and exit-event-loop.
The new (in release 7.0) function initialize-cg allows using Common Graphics in a Lisp that does not include the IDE, or in a standalone application that was not created from an IDE project. Also new are exit-cg and *cg-is-initialized*.
The macro in-cg-process may be used to handle the creation of a Common Graphics process and the call to event-loop for a body of Common Graphics code.
See also the variable *event-loop-processes*.
Generic Function, cg package
Arguments: menu-item
Returns the value of the event-synonym property of the argument menu-item.
The value of this property, if true, should be the key-chord that will invoke this menu-item's command, assuming that the keyboard focus is inside the window whose menu-bar contains this menu-item. An event-synonym always contains a single main non-shift key, plus an optional set of one or more shift keys. If no shift keys are used, then the event-synonym consists entirely of a character name like #\A or a key name like vk-comma or vk-f3. If shift keys are used, then the event-synonym is a list whose members are the names of the shift keys (in any order) and the main non-shift key as the last member. The available shift key names are control-key, alt-key, and shift-key, and they may be used in any combination.
Note that typable characters are normally used only with either control-key or alt-key (or both), since otherwise the characters would not be typable as text (since typing them would activate the menu item rather than entering the character). This is why the first two examples, though legal, are not recommended.
Here are some example event synonyms:
#\A (not recommended since A cannot now be entered as a letter)
vk-period (not recommended since . cannot now be entered as a letter)
vk-f3
(control-key #\A)
(control-key vk-period)
(alt-key shift-key #\A)
(control-key alt-key shift-key vk-f7)
event-synonym is a property of the menu-item class.
See proxy-menu-bar-window, which can be used to redirect keyboard shortcuts to the menu-bar of another window. See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window
Returns true if events are enabled on window and returns nil if events are disabled. See enable-events.
Function, cg package
Arguments: font &key * stream*
Returns the actual font that is being used for some requested font.
The returned font will be equivalent to the requested font if the requested font is an available font, and otherwise will be the approximation to it that the Operating System has decided to use in its place. For example,
(exact-font (make-font-ex nil :|ms sans serif| 8)) may return
#.(make-font-ex :swiss :|ms sans serif| 13) since there are only a couple of sizes for that font face available, and the "family" is always filled in.
For the special system fonts returned by the functions system-font, system-fixed-font, ansi-var-font, and ansi-fixed-font, exact-font can be used to find the face and size that each of these special fonts is mapped to by the Operating System. For example,
(exact-font (system-fixed-font)) may return
#.(make-font-ex :modern :fixedsys 18).NOTE: If neither font nor any other font object that has the same properties (family, face, size, and bold/italic) as font has been assigned to any window yet, then exact-font will return nil because the Operating System has not yet been asked to create a real Operating System font for this font object. So exact-font is normally called on a font that has been assigned to a window with (setf font) or the :font initarg of make-window. If you would like to call exact-font before creating the window that will use the font, as a work-around you could use (setf font) to set the font of (screen *system*) (see screen and *system*) to the font before calling exact-font on the font.
Generic Function, cg package
Arguments: chart-or-plot chart-object exclude?
If the click-to-toggle-inclusion property of a chart-widget or plot-widget is true, then this generic function is called whenever the user clicks on an object in the legend to toggle whether that object is currently included in the chart or plot. An application could add a method for a chart or plot subclass to implement side effects when this happens, such as to re-sort the values.
chart-or-plot is the chart-widget or plot-widget.
chart-object is the chart object whose legend entry was clicked. See chart-objects.
exclude is whether the click toggled the object off rather than on.
Function, cg package
Arguments:
Exits Common Graphics so that no Common Graphics functionality may be used until initialize-cg is called again. It is generally not necessary to call this function, though it does free some operating system resources that were used by Common Graphics objects.
exit-cg also exits from any calls to event-loop in any Common Graphics processes (see About using multiple windowing threads in a Common Graphics application in cgide.html) other than the current process.
Function, cg package
Arguments: dialog exit-item
If dialog is currently popped-up via a call to pop-up-modal-dialog, exit-dialog throws exit-item to 'pop-up-modal-dialog, which causes the function pop-up-modal-dialog to close dialog and return exit-item. If dialog is not currently popped-up, exit-dialog simply returns nil.
Function, cg package
Arguments: &key (process mp:current-process) (exit-code 0)
This function provides a way to exit non-locally from an event-handling loop on request. This is an alternative to exiting based on the conditions that were specified when the event-handling loop was first entered.
If the specified process is currently inside a call to event-loop (see inside-event-loop), then this function will post an event (message) to the process that causes it to return from the call to event-loop when the process reads the posted event. If the process is not inside a call to event-loop, then nothing is done.
The process will not exit its call to event-loop until it returns from handling the event that it is currently handling (if any) and it handles any already-queued events. If the process is inside nested calls to event-loop (which would not normally be the case), then only the innermost call is exited for each call to exit-event-loop.
The value of the process keyword argument should be the process to which the message will be posted. The default value is the current process (the value of *current-process*).
The value of the exit-code keyword argument should be a value that will be returned from the call to event-loop. When a standalone Common Graphics application is generated from a project, then typically either the initial process of the application calls event-loop internally (when a window is returned from the ide:on-initialization function) or else the ide:on-initialization function calls event-loop as the last thing that its body does. In either of these cases, the value returned by event-loop will then be returned to the operating system as the application exits. Therefore, this value normally should be an exit code that would make sense to the operating system (when the specified process is the initial one, which would cause the program to exit). The default is zero, which in most operating systems means that the program completed successfully. An application could return other values when it knows that it is exiting due to a failure.
Function, cg package
Arguments: window
Expands window (if it is shrunken) to fill its previous box. Does nothing if window is already expanded.
The return value of this function is undefined and no meaning should be attributed to the value actually returned. Information about the success or failure of the expansion is not available.
When expand-window is called on a window whose state is :shrunk or :icon, the window is returned to either :normal or :maximized state, depending on which of these two states the window most recently had. If it has not yet had either of these states, then it is put into :normal state. For iconized windows, this emulates clicking on the restore button of the icon.
This operator is now a non-generic function. It calls (setf state), which is a generic function to effect the change in its argument's state. Methods can be added to (setf state) to affect the behavior of this function, as is done in the example below.
When expand-window is called on a window whose state is :shrunk or :icon, the window is returned to either :normal or :maximized state, depending on which of these two states the window most recently had. If it has not yet had either of these states, then it is put into :normal state. For iconized windows, this emulates clicking on the restore button of the icon. Alternately, the new-state argument to (setf state) can be passed as :expanded to achieve the same result; expand-window itself calls (setf state) in this way. (:expanded is not a true state, so the resulting state of the window will be either :normal or :maximized.)
A (setf state) :around method prevents any other non-:around (setf state) methods from being called if the state would not actually be changed by the call. Therefore any methods added by an application do not need to handle this efficiency consideration. This around method also coerces the special :expanded state to either :normal or :maximized and passes that value to the other (setf state) methods that it calls, so any primary, :before, or :after (setf state) methods added by an application will not receive the :expanded state.
The generic function state returns a new second value for the "expanded state" of the window. This value is always either :normal or :maximized. If the current state of the window is :shrunk or :icon, then the value is the state into which the window will be placed if expand-window is called on it or if (setf state) is called on it with the :expanded state. This is also the most recent expanded state that the window was in, or :normal if it has never been expanded. If the current state of the window is :normal or :maximized, the value is the state to which the window was most recently expanded from :shrunk or :icon state.
Here is an example of an added (setf state) :around method that looks at both the old and new states of any frame-window whose state may be changing, and reports any change. Typically several custom methods on shrink-window, expand-window, and so on could be collapsed into such a single (setf state) method. A simpler :after method could be used instead if the old state is not of interest.
The without-package-locks is needed here in a source code file that's not in the cg package only because it specializes a Common Graphics method on a built-in Common Graphics class; normally an application would specialize on its own subclass instead.
The requested-state argument is ignored because it may be :expanded, and we are interested here in the resulting :normal or :maximized state instead. Similarly, some other (setf state) method could coerce the requested state to something else.
ide:eval-in-listener-thread is used to make sure that the printed output always goes to the selected IDE listener pane (and so this method is suitable only for the IDE and not for a generated application). Otherwise, the message will go to the *terminal-io* of whatever thread changed the window state; for example, clicking the minimize button of an IDE window would iconize the window in the IDE GUI thread, for which *terminal-io* is bound to the console, and so the output would appear there.
The prog1 is used to ensure that this (setf state) method returns whatever the next called method returns, though that would normally be the requested-state.
(without-package-locks
(defmethod (setf state) :around (requested-state (window frame-window))
(declare (ignore requested-state))
(let* ((old-state (state window))
new-state)
(prog1 (call-next-method)
(setq new-state (state window))
(unless (eq old-state new-state)
(ide:eval-in-listener-thread
`(format t "~&State of ~s changed from ~s to ~s.~%"
(name ,window) ,old-state ,new-state)))))))Function, cg package
Arguments: window-or-widget
Returns the page-height that has been explicitly specified for window-or-widget with either the (setf page-height) function or the :page-height initarg.
If page-height has not been explicitly specified, then nil is returned.
(The function page-height, on the other hand, always returns the actual effective height that is in use.)
See also default-page-height. (And page-width, explicit-page-width and default-page-width.)
Function, cg package
Arguments: window-or-widget
Returns the page-width that has been explicitly specified for window with either the (setf page-width) function or the :page-width initarg.
If page-width has not been explicitly specified, then nil is returned.
(The function page-width, on the other hand, always returns the actual effective width that is in use.)
See also default-page-width. (And page-height, explicit-page-height and default-page-height.)
Generic Function, cg package
Arguments: widget
Moves widget to the top of the occlusion stack, so that it will appear in front of any overlapping controls. Further, makes widget first in the tab order for its dialog.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the extend-data-to-middle-of-border property of a chart-or-plot. The value may be set at creation time by passing the :extend-data-to-middle-of-border initarg, or any time later by calling (setf extend-data-to-middle-of-border).
A boolean value indicating whether the data area of a chart-or-plot extends to the middle of the body border rather than only to the inner edge of the body border. This choice is a subtle trade-off in the aesthetics of how a chart is drawn, where neatly aligning end tic marks with axes means that data will extend into the middle of a thick axis. The default value is t for just that choice.
This property matters most when a chart body border is thick, and is best described by example. Let's assume that the chart-orientation is :vertical (meaning that the value axis is vertical), that the axis-width of the horizontal item-axis is 7, that the range-bottom of the value-axis is zero, and that a data value of zero is being plotted.
In this example, if extend-data-to-middle-of-border is nil, then a line that is drawn downward to the zero data point will be drawn just to the top of the thick item-axis along the bottom of the chart. Any icon for the zero data point will be centered at the top of the thick item-axis line as well. If this property is true instead, then the line will extend four pixels farther downward to the middle of the thick item axis, and any icon would be centered about the middle of the axis.
A thick tic mark on the vertical value axis will always be vertically centered about the data value to which it points. So if the value of this property is nil, then a thick tic mark at the bottom of the value axis will appear jogged upward from the horizontal item-axis a bit so that its center is aligned with the top of the item-axis, because that is where a data value of zero is plotted. That tends to look a bit sloppy, so the default value of this property is true to instead align a thick end tic mark exactly with an axis of the same thickness. The trade-off is that this causes data values to extend to the middle of the item-axis, which may obscure the data somewhat.
See chart-widget and also .
Function, cg package
Arguments: window-or-screen
Returns the exterior box of window-or-screen. The box is relative to the upper-left corner of the "page" of the parent window, or of the screen if there is no parent window. (A "page" is the logical canvas of a window, on which drawing is done and which is sometimes scrollable. So if the parent window is not scrolled, then the box is relative to the upper-left corner of the parent's interior.) The unit of measurement is pixels.
The screen is the value returned by (screen *system*). See screen and *system*. This function be used with setf to modify the exterior (see track-limits).
To find the exterior without consing a box object, call nexterior instead. To find the exterior that the window would have when its state is :normal, call normal-exterior.
Function, cg package
Arguments: window-or-screen
Returns the height of the exterior box of the window specified by the argument window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*.
Function, cg package
Arguments: window-or-screen
Returns the top-left (a position, see make-position) of the exterior box of window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*.
See nexterior-top-left.
Function, cg package
Arguments: window-or-screen
Returns the width of the exterior box of window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*.
Generic Function, cg package
Arguments: text-edit-pane
This function is meaningful only on the Windows platform, and will return nil elsewhere.
If load-file has been used to load a file into a text-edit-pane, then this function will return the name of the external format that the file was deemed to have, if any, or otherwise the keyword :default. If load-file has not been called on text-edit-pane, then nil is returned.
If load-file has been called on text-edit-pane, then save-file will save the file in this same format, unless the external-format-for-saved-files configuration option is :ask-always (in which case save-file will always ask the user for the format to use).
The only base external format names that might be returned are :unicode (for little-endian 16-bit Unicode), :utf8, :default, or nil when no file has been loaded. These are determined by load-file by checking the byte order marker (BOM) at the beginning of the file, if there is one. If there is no BOM, then :unicode will still be returned if there were any embedded zero bytes in the file, on the assumption that this indicates a Unicode file that has no BOM (though such a file wouldn't necessarily contain any zero bytes.)
When :default is returned, it means that the file was not determined to have either Unicode or UTF8 encoding, and so load-file simply assumed that the file's format matches the external format of the locale with which the Windows operating system is currently booted, and load-file therefore read the file using that external format even though it may not have matched the file's actual format.
The setf of this function could be called to change the external format that save-file would later use. In particular, if a text-edit-pane is reused to begin editing text for a new file, as with a File | New command in an application, then you could set the value to nil to make save-file treat the text as it would the text in a new text-edit-pane.
In the IDE's source code editor, this value can be changed for a particular buffer by typing Control-Shift-CloseSquareBracket, which will display a pop-up menu for selecting either Default, Unicode, or UTF8. (This keystroke is listed in the Help menu | Shortcut Keys dialog as select-external-format-for-save.) Also, the IDE's status bar will indicate the current format for a buffer when you open a file or switch to a different editor buffer.
See also external-format-for-saved-files and *use-unicode-winapi-for-cg*. The configuration option write-bom-to-utf8-files controls whether save-file will write UTF8 byte order marker (BOM) bytes at the beginning of the file, if the file is being saved in UTF8 format.
Generic Function, cg package
Arguments: cg-configuration
This configuration option determines the character encoding that will be used by the function save-file for saving the text that's in a text-edit-pane to a file. This applies only on the Windows platform, because CG/JS always uses the utf-8s external-format (unless the stream-external-format of the text-edit-pane is explicitly changed).
This option affects the IDE's source code editor because it calls save-file whenever it saves a file.
This option is generally used only when saving a text-edit-pane's text to file for the first time, rather than when re-saving a file that was loaded and edited. Specifically, when load-file is called to load text into a text-edit-pane, the external format that was used for reading the file is stored as the external-format-for-save property of the text-edit-pane, and save-file will later use that same external format to update the file. The options below will be used only if the external-format-for-save property is nil (either because no file was loaded or because you've set that property back to nil), or if this option value is :ask-always.
Here are the valid values for this option. Some of these are the same as valid stream-external-format values.
:default -- Saves a new file using the external format of the locale with which the Windows operating system is currently booted. This is the default value, and is what was always done in Allegro releases prior to 9.0.
:unicode -- Saves a new file in a little-endian 16-bit Unicode format.
:utf8 -- Saves a new file in UTF8 format.
:ask-new -- When saving a new file, shows a modal dialog asking which of the above formats to use.
:ask-always -- Always shows a dialog asking which format to use when saving a file, even when updating a file that had been loaded with load-file.
See also automatic-font-changing and *use-unicode-winapi-for-cg*. The configuration option write-bom-to-utf8-files controls whether save-file will write UTF8 byte order marker (BOM) bytes at the beginning of the file, if the file is being saved in UTF8 format.
See also load-utf8-if-no-bom and ide:compile-files-as-utf8.
Function, cg package
Arguments: filename &optional (icon-number 0) size
This function is specific to the Windows platform, and will return an unspecified value elsewhere. On other platforms, pixmaps can be used where icons are used on Windows.
Returns an icon handle, which can be used as the icon of a window, the value of a static-picture control, or the title of a picture-button control.
The arguments are:
filename, which must be a string indicating a file with a .ico, .dll, or .exe extension; an icon is loaded from this file.
icon-number, which is used for files containing multiple icons; its value should be a non-negative integer indicating the index of the icon to load, where zero indicates the first icon in the file; defaults to zero.
size, which is a keyword or nil that specifies whether to extract a large or small icon. If :large, then a large icon is returned if the file contains one, and otherwise nil is returned. If :small, then a small icon is returned if the file contains one, and otherwise nil is returned. If nil (the default), then a large icon is returned if the file contains one, and otherwise a small icon is returned.
A note about small icons in Windows: If an icon file in Windows
contains only a small icon, and the *size* argument is `nil`, then
the small icon will be returned, but will be stretched to the
large icon size. Therefore, to extract a small icon at its
natural size in Windows, you must pass *size* as `:small`.See cg-icons.html.
Generic Function, cg package
Arguments: text-edit-pane
face returns two values: (1) the font face of the first character of the selected range of text-edit-pane as a keyword, and (2) true if and only if the entire selection is the same font face.
(setf face) sets the font face of the selected range of text-edit-pane to a new value, which should be a keyword that names an installed font face.
A text-edit-pane argument must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: control
Asks the operating system what the true value of dialog-item is, sets the official value property of the widget to that value, and returns the value.
Typically this function is not needed, since the operating system sends messages to Common Graphics when a control's value has changed and the value property is updated at that time. In certain unusual circumstances, however, the value property may not be out of date because the change message from the operating system either has not arrived yet or has been overridden in some way.
Here are two cases where this function may be needed:
The user is typing into an editable-text control. The control's delayed property is turned on, which means that the value property of the control is updated only when the keyboard focus moves from the control. But while the focus is still in the control, the user presses the main ENTER key, which invokes the on-change handler of the default-button on the same dialog. This on-change handler reads the current value of the editable-text control, but this value is not up to date because the control still has the focus. To prevent this problem, the default-button's on-change handler could call fetch-control-value on the editable-text before it reads its value.
An on-click event handler that calls drag-and-drop is added to an item-list control. Normally the operating system sends a message that the value of an item-list control has changed only when the mouse button is released, but in this case drag-and-drop will grab the mouse-left-up event to determine when to stop dragging and so Common Graphics is never told that the value has changed. Calling fetch-control-value on the item-list just before calling drag-and-drop will prevent this problem. (Actually drag-and-drop now will always call fetch-control-value internally. So this case does not need to be handled by an application, though it is still an example of situations where fetch-control-value may be needed.)
Currently fetch-control-value is implemented for these controls where a need has arisen at some point: editable-text, multi-line-editable-text, single-item-list, multi-item-list, and combo-box. If fetch-control-value is called on any other control, it is assumed that the current value property of the control is up-to-date and this value is simply returned.
Generic Function, cg package
Arguments: object
Returns the file associated with the argument, if there is one. Returns nil if there is no associated file. If object is a project module, returns the .cl file associated with module. The module will also have in the same directory an associated .bil and may also have a .bml file. If object is a text-edit buffer associated with a file, returns that file.
Generic Function, cg package
Arguments: configuration
Returns (or sets with setf) the byte length of the buffer that is used for returning the selected pathnames from calls to ask-user-for-existing-pathname, from calls to ask-user-for-existing-pathname and ask-user-for-new-pathname. This value is used only on the Windows platform.
The interesting case is when ask-user-for-existing-pathname is called with the multiple-p option to allow the end user to select any number of files. If Allegro CL made the buffer large enough to hold the largest set of pathnames that might be selected in any application, a static buffer would make all standalone applications significantly larger, or a dynamically-allocated buffer might even make the dialog noticeably slower to appear. Therefore we use a modest-sized buffer by default, but also provide this configuration option for an application to increase the size of the buffer if needed.
The initial buffer would hold fifty< pathnames of maximum length. Since the maximum pathname length in the Windows API is currently 260, this makes the default buffer 13000 bytes in size. An application in which the end user may select a set of pathnames whose combined length is larger should increase this buffer size with a form such as
(setf (file-selection-buffer-size (configuration *system*))
new-size)file-selection-buffer-size is a property of the configuration class.
Generic Function, cg package
Arguments: printer
Returns the value that was passed as the filename keyword argument to open-stream when creating a printer stream, if the filename was specified in that manner. nil is returned if no filename has been specified. t is returned if the user specified a file name interactively by using the Print to File option on the printer dialog.
Ideally this property would hold the path that a user specifies when exiting the Print Job dialog after checking the Print to file check-box, but in fact there is no way in Windows to retrieve this path. It may be preferable to pass the filename argument to open-stream. See pop-up-printer-job-dialog for related arguments.
This generic function is not setf'able.
Generic Function, cg package
Arguments: module
Returns all files associated with module. files is a property of the project class. Can be used with setf to specify a new list of files.
Function, cg package
Arguments: graphical-stream vertices
This is like draw-bezier-curve except that it fills the interior of the curve.
This is implemented only in CG/JS mode, and will do nothing in Windows mode.
Generic Function, cg package
Arguments: stream box
Draws the specified filled box on stream. stream should be a graphical-stream. box must be a box object, such as created by make-box.
Contrast with erase-contents-box which erases the filled box from stream.
To use individual coordinates rather than creating position objects, see fill-box-x-y.
Generic Function, cg package
Arguments: stream left top right bottom
Fills a rectangular area on stream from an upper-left position at (left, top) to a lower-right position at (right, bottom). stream should be a graphical-stream. The other arguments should be integers. To use a box object rather than individaul coordinates, see fill-box.
The filled area will include the pixels where the x coordinate is equal to left and those where the y coordinate is equal to top, but not the pixels where the x coordinate is equal to right or those where the y coordinate is equal to bottom.
Generic Function, cg package
Arguments: stream center radius
Draws the specified filled circle defined by center and radius on stream. center must be a position (see make-position). stream should be a cg-stream.
Contrast with erase-contents-circle which erases the filled circle from stream.
Generic Function, cg package
Arguments: stream center radius start-angle length-angle
Draws the specified filled circle sector on stream. A circle-sector is an arc with length length-angle starting at start-angle on the circle defined by radius and center, along with the radii connecting the vertices of the arc with the center (i.e. a shape like a piece of pie).
center must be a position (see make-position). stream should be a cg-stream.
Angles are measured in degrees clockwise from the 3 o'clock position (that is, along or parallel to the x axis). The endpoint coordinates may be determined by calling ellipse-start-and-end.
Contrast with erase-contents-circle-sector which erases the filled circle sector from stream.
Generic Function, cg package
Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle
Draws the specified filled ellipse on stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise.
center should be a position (see make-position). stream should be a cg-stream.
Contrast with erase-contents-ellipse which erases the filled ellipse from stream.
Generic Function, cg package
Arguments: stream center smaj-axis smin-axis smaj-axis-angle start-angle length-angle
Draws the specified filled ellipse sector on stream. An ellipse-sector is an ellipse-arc with the endpoints of the arc connected to the center of the ellipse, like a piece of an elliptical pie.
The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. The portion of the ellipse drawn is the sector starting at start-angle (0 is the x axis when the center is the origin) through the length-angle.
Angles are measured in degrees clockwise from the 3 o'clock position (that is, along or parallel to the x axis). The endpoint coordinates may be determined by calling ellipse-start-and-end.
center should be a position (see make-position). stream should be a cg-stream.
Contrast with erase-contents-ellipse-sector which erases the filled ellipse from stream.
Generic Function, cg package
Arguments: multi-picture-button
Returns the value of the fill-order property of the argument. The value can be :lengthwise or :breadthwise.
When :lengthwise, the buttons in the range of the multi-picture-button control are first laid out in a line along the longer dimension (the length) of the control, then in another line next to that, and so on. When :breadthwise, the buttons are first laid out along the shorter dimension (the breadth).
fill-order is a property of the multi-picture-button class.
Generic Function, cg package
Arguments: stream vertices
Draws the specified filled polygon on stream. A polygon is specified by vertices, which should be a sequence (list or vector) of positions (see make-position). Lines connect each vertex with the next one in the sequence, and a line is drawn connecting the final vertex with the first vertex.
stream should be a cg-stream.
Contrast with erase-contents-polygon which erases the filled polygon from stream.
Generic Function, cg package
Arguments: stream top-left width height corner-width corner-height
Draws a filled rounded box on stream with top-left, width, and height indicated. A rounded box has rounded corners. The corner-width and corner-height arguments indicate the width and height of an ellipse that is used to draw the corners (and so the corners themselves are actually only half that wide and tall).
stream should be a cg-stream.
See also erase-contents-rounded-box, and draw-rounded-box.
Generic Function, cg package
Arguments: header-info
Returns the value of the fill-space property of header-info.
This property determines whether some or all of the extra horizontal space in a header-control is distributed to this particular header when the header-control is created or when one of the borders between headers is moved by the user. By default, only the last (rightmost) header consumes any extra space, but other headers may initially share in any extra space if the :fill-space initarg is passed as true when creating the header-info instances. If the fill-space property of a header-info is set to true sometime after creation, then the header will share in extra space only when the user drags a header divider.
fill-space is a property of the header-info class.
Generic Function, cg package
Arguments: stream
Returns (or sets with setf) the fill-texture of a stream. The fill-texture is used by drawing functions that fill an area of a stream (as opposed to drawing lines), and may be used to fill with a pattern rather than with a solid color. The pattern will automatically be clipped at the edge of the area being filled, even if it is irregularly shaped. Functions that use the fill-texture of a stream include fill-box, fill-polygon, fill-circle, fill-circle-sector, fill-ellipse, fill-ellipse-sector, fill-rounded-box, and flood-fill.
The value should be any Common Graphics pixmap (see cg-pixmaps.html) or one of the special symbols discussed further below. (For backward compatibility, the value may alternately be a texture, though it will draw correctly only if its width is a multiple of 32.)
The default value is the keyword :solid, which effectively means that the stream does not have a fill texture, and so the filling functions will simply draw in the current foreground-color of the stream.
If the value is a pixmap, then it behaves differently depending on whether it is monochrome. If the pixmap's bits-per-pixel property is 1 (indicating a monochrome pixmap), then the filling functions will draw the pixmap in the stream's current foreground-color wherever the pixmap has a "1" pixel, and in the stream's current background-color wherever it has a "0" pixel. Otherwise the pixmap will be drawn in its own colors, as with copy-to-stream.
Windows only: As an alternative to specifying a custom pixmap, any of several special built-in fill-textures may be used by specifying a particular keyword symbol rather than a pixmap. These symbols include :12%foreground, :25%foreground, :37%foreground, :50%foreground, :62%foreground, :75%foreground, and :87%foreground. These fill-textures draw a pattern consisting of the indicated portion of pixels being drawn in the stream's current foreground-color, with the remaining pixels being drawn in the background-color. The foreground-color pixels are intermingled amongst the background-color pixels as evenly as possible, to "dither" the two colors. For example, if a stream's current background-color is yellow, its foreground-color is dark-red, and its fill-texture is the symbol :25%foreground, then filling functions will draw three-quarters of the pixels in the filled area as yellow, with one-quarter of the pixels sprinkled throughout as red.
A second set of special fill-texture symbols draw parallel straight lines in the foreground-color of a stream, with the remaining pixels in the background-color. These values are :horizontal, :vertical, :left-diagonal (drawing lines from upper-right to lower-left), and :right-diagonal (drawing lines from upper-left to lower-right).
;; This example uses the built-in :left-diagonal fill-texture.
(let* ((frame (make-window :filler :class 'bitmap-window
:interior (make-box 100 100 300 300)))
(drawing-pane (frame-child frame)))
(setf (foreground-color drawing-pane) red)
(setf (background-color drawing-pane) yellow)
(setf (fill-texture drawing-pane) :left-diagonal)
(fill-ellipse drawing-pane (make-position 100 100) 80 50 0)
(draw-ellipse drawing-pane (make-position 100 100) 80 50 0))
;; This example uses a multicolor pixmap.
(let* ((frame (make-window :filler :class 'bitmap-window
:interior (make-box 100 100 300 300)))
(drawing-pane (frame-child frame)))
(setf (fill-texture drawing-pane)(find-pixmap :melvin))
(fill-ellipse drawing-pane (make-position 100 100) 80 50 0)
(draw-ellipse drawing-pane (make-position 100 100) 80 50 0))
;; This example uses a monochrome pixmap.
(let* ((frame (make-window :filler :class 'bitmap-window
:interior (make-box 100 100 300 300)))
(drawing-pane (frame-child frame)))
(setf (foreground-color drawing-pane) dark-blue)
(setf (background-color drawing-pane) cyan)
(setf (fill-texture drawing-pane)
(make-instance 'pixmap
:bits-per-pixel 1
:contents '(#*000111100000
#*001000010000
#*010000001000
#*100000000111
#*010000001000
#*001000010000)))
(fill-ellipse drawing-pane (make-position 100 100) 80 50 0)
(draw-ellipse drawing-pane (make-position 100 100) 80 50 0))
#|
These are used as the bar-fill-textures property in the chart-widget
example in the Navigator dialog.
These pixmaps specify their own colors, unlike the 1-bit-per-pixel
pixmap above that uses the window's current foreground-color and
background-color. You might want to use the actual :contents values
shown here (or variations of them) with other colors that you prefer.
|#
(make-instance 'pixmap
:name :diagonals
:bits-per-pixel 8
:colors (vector light-green dark-green)
:contents '((1 0 0 0 0 1)
(0 0 0 0 1 1)
(0 0 0 1 1 0)
(0 0 1 1 0 0)
(0 1 1 0 0 0)
(1 1 0 0 0 0)))
(make-instance 'pixmap
:name :dots
:bits-per-pixel 8
:colors (vector light-yellow red)
:contents '((0 0 0 1 0 0 0 0)
(0 0 0 0 0 0 0 1)
(0 1 0 0 0 0 0 0)
(0 0 0 0 0 1 0 0)))
(make-instance 'pixmap
:name :spots
:bits-per-pixel 8
:colors (vector cyan dark-blue)
:contents '((1 0 0 0 0 0 0 1 1 1)
(0 0 0 1 1 0 0 0 1 1)
(0 0 1 1 1 1 0 0 0 0)
(0 0 1 1 1 1 0 0 0 0)
(0 0 1 1 1 1 0 0 1 1)
(1 0 0 1 1 0 0 1 1 1)))
(make-instance 'pixmap
:name :hexagons
:bits-per-pixel 8
:colors (vector cyan dark-blue)
:contents '((0 0 0 1 1 1 1 0 0 0 0 0)
(0 0 1 0 0 0 0 1 0 0 0 0)
(0 1 0 0 0 0 0 0 1 0 0 0)
(1 0 0 0 0 0 0 0 0 1 1 1)
(0 1 0 0 0 0 0 0 1 0 0 0)
(0 0 1 0 0 0 0 1 0 0 0 0)))
(make-instance 'pixmap
:name :squares
:bits-per-pixel 8
:colors (vector yellow dark-yellow)
:contents '((1 0 0 0 0 0)
(1 0 0 0 0 0)
(1 0 0 0 0 0)
(1 0 0 0 0 0)
(1 0 0 0 0 0)
(1 1 1 1 1 1)))
(make-instance 'pixmap
:name :eksuz
:bits-per-pixel 8
:colors (vector light-gray red)
:contents '((1 0 0 0 0 0 1)
(0 1 0 0 0 1 0)
(0 0 1 0 1 1 0)
(0 0 0 1 0 0 0)
(0 0 1 0 1 0 0)
(0 1 0 0 0 1 0)
(1 0 0 0 0 0 1)))
Function, cg package
Arguments: stream
Returns (or sets with setf) the current origin of the fill-texture of stream. stream may be any cg-stream, and the value should be a position object (see make-position). When filling functions such as fill-box are called on the stream, the current fill-texture of the stream will be shifted rightward and downward from its usual position by the amount indicated by this position.
CG/JS Note: Setting this origin currently has no effect in CG/JS mode. But it's probably not important because the JavaScript case doesn't have the problem of offsetting the texture differently according to how far the window is scrolled, leading to misaligned drawing when a scroll re-draws only the part that just got scrolled into view.
Generic Function, cg package
Arguments: stream
Use of this function has been deprecated. It was useful only for non-NT versions of Windows (through win98 and winME), which Allegro no longer supports.
Returns two values, which are the recommended width and height (in pixels) for the fill-texture of a stream on the platform being used. Other sizes may also work, depending on the platform.
Generic Function, cg package
Arguments: key &optional (subkey (default-application-window-subkey))
Returns a window that was cached by calling add-application-window (including calls to that function that were made by find-or-make-application-window).
If key and subkey are eq to values that were passed for some window to add-application-window, and that window has not been closed, then that window is returned. Otherwise nil is returned.
Typically you would pass the name of the window as the key argument to match the default value of add-application-window, and let the subkey argument in both functions default to the value returned by default-application-window-subkey. This would find any window with a given name on which you have called add-application-window in the same process.
See also add-application-window and remove-application-window.
Generic Function, cg package
Arguments: list-view column-name
Returns the list-view-column of list-view whose programmatic name is column-name, or nil if none.
Function, cg package
Arguments: name dialog-or-name
Returns the component (dialog-item) whose name is name and which lies on the dialog specified by the second argument. The name property of a dialog-item should be a symbol, and is established by specifying a value for the :name option to the (make-instance '[dialog-item]) form which created the component.
The dialog-or-name argument can be either the dialog object or, in some cases, the name of the dialog. (The name of the dialog will suffice only if the parent of the dialog is (screen *system*) (see screen and *system*) or (development-main-window *system*).
Generic Function, cg package
Arguments: name
Finds the cached mouse cursor with the specified name. The cursor could then be passed to (setf cursor) to use that cursor in a particular window, widget, or hotspot.
The value should be a keyword whose name is the name of one the cursor variables that are listed in the section on mouse cursors in cg-pixmaps.html.
Generic Function, cg package
Arguments: list-view &optional (item-name (first (value list-view)))
Returns the list-view-item of list-view whose programmatic name is item-name. Returns nil if no such item can be found. Item-name defaults to the first of the list-view's currently selected values.
Generic Function, cg package
Arguments: rich-edit-pane &key (link-color (link-color rich-edit-pane)) append
Finds all of the substrings of a certain color on rich-edit-pane (which must be an instance of the rich-edit-pane class) and returns a list indicating the starting and ending indices of each string. Each member of the returned list represents one link as a list of its starting index, its ending index, the string itself, and the link color. The list of links is in the order that the links appear in the rich-edit-pane.
link-color should be an rgb color object, and defaults to the link-color of the window, which defaults to blue.
If the append keyword argument is nil (the default), then any previously-found links for this rich-edit-pane will be discarded, leaving only the links found by this call as the links of the window. If append is true, then the links found by this call will be appended to the window's current links. This allows setting up links in multiple colors by calling find-links a number of times with different colors, passing append as true on all but the first call. The function links could be called at any later time to retrieve the combined list of links.
For example, find-links might return the following list when passed a rich-edit-pane with three blue strings in it:
((10 16 "mumble") (36 39 "foo") (120 134 "how about that"))find-links caches the returned list as the links property of the rich-edit-pane, so that it may be referenced later without re-searching for the links.
Finding links is a relatively slow procedure, and may not be fast enough to do on the fly as the end user open rich text files or clicks on links. Therefore it is recommended that find-links be called when a file is saved, and the list of returned links saved somewhere so that when the file is reloaded, the list of links can be retrieved and re-associated with the rich-edit-pane.
rich-edit-save and rich-edit-save-as will call find-links automatically if the save-links property of the rich-edit control or rich-edit-pane window has been turned on (it is off by default). After it finds the links, it saves them in a file with the same path as the rich text except with a .lin extension. This file is then read back by rich-edit-open if save-links is turned on so that the links may be used without re-searching for them when the file is opened.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: &key (top-directory "/")
This function is no longer used. It was related to the GTK version of CG, which is no longer supported.
Generic Function, cg package
Arguments: name scope
Returns an object whose name is name and for which scope is some ancestor of the object, or nil if no such object is found. By "ancestor", we mean either the parent or owner of the object, or an ancestor of the parent or owner. In addition, if the name argument is the name of the scope object itself, then that object is returned. name is generally the symbol that was passed as the value of the name initarg when creating the object.
The object to be found and the ancestor that defines the scope of the search may be either:
a window and an ancestor window or screen,
a dialog-item and an ancestor window or screen,
a menu and an ancestor menu,
a menu-item and an ancestor menu,
any of those objects and a list of possible ancestors.
The screen is the value returned by (screen *system*). See screen and *system*.
If this function is used, it may be necessary to use unique names across all windows, dialog-items, menus, and menu-items in your application. If more specific finder functions are used instead, then it is necessary to use unique names only among the siblings that share a particular parent or owner object. The more specific finder functions include:
(There is only a partial overlap between the kinds of objects that these functions find and the ones found by find-named-object.)
Generic Function, cg package
Arguments: name make-function &rest args
Returns a window that is intended as a non-modal window for an application. If the window has previously been created by calling find-or-make-application-window or add-application-window and it has not been closed, then the existing window is returned. Otherwise make-function is called to create the window, and that new window is returned.
This function calls find-application-window to find an existing matching window if any. It will pass name as the key argument to find-application-window, and pass the current process as the subkey argument, and t as the always argument.
name is an arbitrary symbol for identifying the window. No two windows that are made with find-or-make-application-window or find-or-make-pop-up-window should use the same name.
make-function should be the name of a function that takes args as its argument list, and which makes and returns a window whose name is name.
See also find-application-window, add-application-window, and remove-application-window.
Generic Function, cg package
Arguments: name make-function owner
Returns a window that is intended as a modal dialog for an application. If the window has previously been created by calling find-or-make-pop-up-window, it has not been closed, and its owner is the owner being requested here, then the existing window is returned. Otherwise make-function is called to create the window, and that new window is returned.
This function does not call find-application-window (as find-or-make-application-window does) to find an existing window. The only pre-existing window that this function would return is one that was created by a call to find-or-make-pop-up-window in the same process and with the same name and owner arguments.
Name is an arbitrary symbol for identifying the window. No two windows that are made with find-or-make-pop-up-window or find-or-make-application-window should use the same name.
make-function should be the name of a function that takes a single argument, which is owner, and which makes and returns a window whose name is name and whose owner is owner.
Generic Function, cg package
Arguments: outline &optional item-value &key (key #'identity) test only-after-index
Finds and returns the first currently visible outline-item on outline whose value is item-value. If no such outline-item is found, then nil is returned.
key and test are used as in find and related functions for finding the matching value. The value of key should be a function (suitable as the first argument to funcall) of one argument that is applied to a candidate value before comparing it with item-value. The comparison is done with the value of test, which should be a function (suitable as the first argument to funcall) that accepts two arguments and returns true if the arguments should be considered identical. test defaults to the value of the on-change-test event property of outline-item.
If only-after-index is true, it should be a non-negative integer indicating the position of some outline-item to make the search begin with the item just following it (and proceeding downward as usual).
Generic Function, cg package
Arguments: name &key create (use-handle nil use-handle-supplied)
Returns the cached pixmap named by name which can be a symbol or a pathname namestring. If a namestring, the create argument should be true, and the pixmap is read from the file and cached as if with cache-pixmap. The use-handle argument, if true, tells the system to use the pixmap handle, creating it if necessary.
The system remembers the pathname namestrings of cached pixmaps read from files so if this function is called with name a pathname namestring for a second time, the file will not be read again but the cached pixmap will be used. The idea is that you can have various calls to find-pixmap with name a pathname namestring and create true in your code. The first one evaluated reads the pixmap and caches it. All subsequent calls use the cache pixmap so the behavior is the same no matter in what order the calls are actually encountered by the system.
Generic Function, cg package
Arguments: object name
Returns the property object which is the property named by name (a symbol) of object. Note that this does not return the value (see property-value) but the property object.
Function, cg package
Arguments: parent-stream
If there are any rich-edit-panes (instances of the rich-edit-pane class) on parent-window that have had the keyboard focus, then the rich-edit-pane on parent-window that most recently had the focus is returned. (This will be the one that has the focus now if one does.) Otherwise the parent window of parent-window (if it has a parent window) is similarly searched, returning the most-recently-focused rich-edit-pane if any, and then the parent of that window (if any) is searched and so on through the top-level window. (Whenever the parent-window is a frame-with-single-child window, the frame-child of the parent-window is searched.) If no rich-edit-pane that has had the keyboard focus is found, then nil is returned.
This function is chiefly used internally to find the rich-edit-pane that should be affected by one of the rich-edit "helper" controls such as a rich-edit-multipic, but could also be used by applications. Searching successive parent windows allows a helper control to be on a toolbar of the window containing the rich-edit-pane, for example.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: name object
Finds and returns an object whose programmatic name is name and whose parent is the parent of object. May be used on a dialog-item, window, tab-info, header-info, or any grid section (grid-column-section, grid-row-section, grid-column, or grid-row). Returns nil if there is no such object.
Generic Function, cg package
Arguments: tab-control &optional (tab-id (value tab-control))
Finds the tab on tab-control identified by tab-id. If tab-id is not specified, the currently visible tab (which is the value of tab-control) is returned. See the description of the tab-control control.
Function, cg package
Arguments: parent-stream
If there are any text-edit-panes (instances of the text-edit-pane class) on parent-window that have had the keyboard focus, then the text-edit-pane on parent-window that most recently had the focus is returned. (This will be the one that has the focus now if one does.) Otherwise the parent window of parent-window (if it has a parent window) is similarly searched, returning the most-recently-focused text-edit-pane if any, and then the parent of that window (if any) is searched and so on through the top-level window. (Whenever the parent-window is a frame-with-single-child window, the frame-child of the parent-window is searched.) If no text-edit-pane that has had the keyboard focus is found, then nil is returned.
Function, cg package
Arguments: name
Returns the most recently-created timer whose name is name, if any, or nil otherwise. Timers normally should be given unique names to avoid ambiguity.
See cg-timers.html for more information on timers.
Function, cg package
Arguments: window-name &optional (*parent-or-owner8 (screen system)) &key owned-p
Returns the window whose name is name and whose parent or owner is parent-or-owner (which can be nil if there is no such window). The default value of parent-or-owner is the screen, and so this argument need not be passed in order to find any top-level window (since the parent of a top-level window is always the screen). The screen is the value returned by (screen *system*). See screen and *system*.
window-name should be the symbol that was passed as the value of the name initarg to make-window (or passed to (setf name) to rename the window later). The parent-or-owner should either be the window or screen that was passed as the value of the owner argument to make-window, or alternately the screen in the case of an owned top-level window (whose owner is another window but whose parent is the screen).
If owned-p is nil (the default), then only child windows of parent-or-owner are searched. If true, then only non-child owned windows of parent-or-owner are searched. A true owned-p argument is useful only when parent-or-owner is a top-level window or the screen, because child windows cannot have non-child owned windows. (A non-child owned window is created by passing the child-p initarg of make-window as nil, along with a top-level window for the owner argument.)
A more general function for finding objects from their names and ancestor objects is find-named-object.
It is dangerous to use find-window to find a top-level window that is designed interactively as a form window in a project in the IDE. (Though if the window is a child window at run time and you pass the optional parent-or-owner argument, then there is no problem.)
The reason is that a form window in a project and its running window have the same name, and find-window will return whichever one it happens to find first. So when running a project in the IDE, find-window could return the form window, and if your code modifies that window then it could modify the form window itself and leave the project confused.
If your project uses the default ide:on-initialization function, and therefore does not have an explicit call to make the main window, then it is best to use find-application-window rather than find-window to get a handle on the main window. In other cases it is usually best to save the window that's returned when calling the function that creates the window. (You can use find-application-window with other windows as well, though you may need to set things up with a call to add-application-window when creating the window.)
Generic Function, cg package
Arguments: window-or-widget
Returns an index indicating the line of text that is currently scrolled to the top of the window or widget. Zero indicates the first line of text.
window-or-widget may be a text-edit-window, text-edit-pane, multi-line-editable-text, single-item-list, multi-item-list, outline, or scrolling-static-text.
To scroll a line to the top, call set-first-visible-line.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the fit-chart-items property of a chart-widget. The value may be set at creation time by passing the :fit-chart-items initarg, or any time later by calling (setf fit-chart-items).
fit-chart-items is a boolean value indicating whether the chart items of a chart-widget are spaced apart by an amount that causes the items to exactly fill the length of the item axis. The default value is nil.
Turning this property on can make a chart look neater as long as it does not cause the items to be squeezed too closely together or stretched too far apart.
When this property is nil, item spacing is determined by a combination of other properties, largely to prevent the graph objects and axis tic mark labels from running into each other. These properties include value-spacing, bar-width, bar-spacing, values-are-stacked, minor-tics-per-major-tic, major-label-frequency, minor-label-frequency, major-label-min-spacing, minor-label-min-spacing, major-label-font, minor-label-font, major-label-wrapping, and minor-label-wrapping.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: configuration &optional default
Returns the value of the fixed-font property of configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
fixed-font is a property of the configuration class.
Generic Function, cg package
Arguments: tab-control
Returns the value of the fixed-width property of tab-control. This property determines whether tabs on the tab-control all have a specified fixed width, or whether each tab's width is automatically adjusted so that its label displays entirely. In either case, the tab-control automatically arranges the tabs into rows according to how many will fit in each row.
The fixed-width property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :fixed-width initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
fixed-width is a property of the tab-control class.
Generic Function, cg package
Arguments: window &optional value
Tells the system that the user has completed interaction with a modal dialog, and so the dialog should go away and the call to pop-up-modal-dialog that invoked the modal dialog should now return. A call to flag-modal-completion is not a non-local exit like a throw; it merely sets a flag that is noticed asynchronously after the event-handling code that calls flag-modal-completion has exited.
flag-modal-completion is called internally if the on-change event handler function for a control returns a true second value, or if the default on-change event handler function is used with a default-button or cancel-button. An application can also call flag-modal-completion explicitly to end interaction with a modal dialog. For example, the on-double-click event handler function for an item-list control could call flag-modal-completion with the value of the item-list to be returned from the call to pop-up-modal-dialog.
window is the modal dialog. If window is not presently being invoked modally with pop-up-modal-dialog (see is-modal), then flag-modal-completion simply does nothing.
value is an arbitrary value that will be returned from pop-up-modal-dialog.
A multiprocessing note: flag-modal-completion will work only if it is called in the same process that called pop-up-modal-dialog, because each process maintains its own independent stack of currently-invoked modal dialogs. If called in a different process, it will do nothing. If you are attempting to programmatically exit a modal dialog from a different process, this probably indicates that the dialog should not be modal at all. A modal dialog is intended to be exited only by a user interactively manipulating its widgets (where the on-change or other event handler of one of the widgets could call flag-modal-completion).
Generic Function, cg package
Arguments: texture
Replaces the texture-array of texture with a new array that reverses the order of the bits within each byte. This function is sometimes needed due to the fact that the Operating System expects the bits in a monochrome bitmap array to be in the reverse order of what they are in an Allegro bit array.
If a texture is created by calling load-pixmap, then flip-monochrome-bytes is called internally as needed, and so the application does not need to do so. But if a monochrome (1-bit-per-pixel) texture is defined as a static bit array, then the application will need to explicitly call flip-monochrome-bytes on the texture once at some point before copying it to a window.
Generic Function, cg package
Arguments: stream position &key border-color
CG/JS Note: This function exists only for the Windows platform, and should not be called in CG/JS mode.
Changes an arbitrary contiguous set of pixels of stream to the current foreground-color of stream, by starting at the pixel specified by position and changing the color of that pixel and its immediately neighboring pixels (vertical and horizontal only) when their current colors meet certain criteria. Whenever a pixel is changed, additional branches of the search consider that pixel's immediate neighbors as well. The activity stops only when every branch of the search either has encountered a pixel that should not change color or has already been considered, or has gone off the edge of the stream or its current clipping-box.
If border-color is nil (which is the default), then only pixels that are the same color as the pixel at position are changed. Intuitively, the area that is currently a single color and includes the pixel at position is changed to the current foreground-color of the stream. If the pixel at position is already the current foreground, then nothing is done.
If border-color is instead an RGB color object (see make-rgb), then all pixels except those that are the specified border color are changed. Intuitively, this fills an area that is completely surrounded by the border color and contains the pixel at position, if there is such a boundary, and otherwise changes all of the stream's pixels except those that are of the border color (or in areas bounded by the border color) to the foreground color.
Use with-foreground-color around a call to flood-fill to change the pixels to some arbitrary color.
position should be a position (see make-position). stream should be a cg-stream. For streams other than bitmap-panes, nothing will be done if the initial position is not currently visible or is otherwise outside of the stream's current clipping-box, and filling will never proceed through an area that is clipped to continue on another visible area of the window. This is not an issue when filling a bitmap-pane, bitmap-stream, printer, or the screen unless an explicit clipping-box has been set. (Drawing on the screen requires a with-device-context wrapper.)
Note that this Common Graphics function directly calls a function supplied by the operating system, and Common Graphics has no control over the subtle choices in the implementation of this algorithm. In Windows, this function is ExtFloodFill. The documentation for this function implies that there may be cases where the operation will not complete, which are possibly due to the stack being depleted by a huge fill. Also, one small difference with the Common Graphics function is that when no boundary color is specified, flood-fill always uses the current color of the pixel at position as the color to change, rather than requiring that the application specify this color and then doing nothing if a different color is specified.
Generic Function, cg package
Arguments: calendar-widget
The color in which to draw a focus rectangle around a calendar widget, when show-focus-box is true. The value should be an rgb instance, as made with make-rgb.
See also the calendar class and the function ask-user-for-date.
Function, cg package
Arguments: grid-widget
Returns multiple values to indicate where the keyboard focus currently is within the grid-widget passed as the single argument. The values returned are
If the row-section that contains the grid's focus has no subsections, then the returned row and row-index will each be nil. Similarly, if the column-section that contains the grid's focus has no subsections, then the returned column and column-index will each be nil.
Otherwise, the row-section, column-section, row, and column will always be instances of the grid-row-section, grid-column-section, grid-row, and grid-column classes (respectively) or their subclasses, and the row-index and column-index will each always be a non-negative integer indicating which replication of the row or column has the grid's focus (this is always 0 for a non-replicated row or column).
The above values are returned even when the grid-widget itself does not have the keyboard focus, indicating to where the keyboard focus will return if and when it returns to the grid-widget. If the grid-widget has not yet had the keyboard focus, then the first replications of the first subsections of the first row-section and column-section will be returned.
To move the focus to a different grid-widget cell programmatically, call set-focus-cell.
Generic Function, cg package
Arguments: grid-widget
Returns the column-section of grid-widget (a grid-widget) that either has or most recently had the keyboard focus, or else nil if grid-widget has not yet had the keyboard focus.
This is the column-section that will get the keyboard focus the next time the grid-widget itself gets the keyboard focus.
Function, cg package
Arguments:
Returns the control that currently has the keyboard input focus. Returns nil if no control has keyboard focus
Generic Function, cg package
Arguments: outline
Returns the index of the focused outline-item of outline. The index is determined by the current appearance of the outline. The topmost visible item, has index 0 and the indices increase as you move down the visible items regardless of their indentation. Thus, if an item above the item with index 7, say, is expanded, index 7 will refer to a different item.
See also focused-outline-item.
Generic Function, cg package
Arguments: tab-control
Returns the value of the focus-on-click property of tab-control. This property determines whether a tab-control will receive the keyboard focus when it is clicked.
The value can be t or nil. If it is t, the tab-control control will have the keyboard focus when users click on it. This allows selecting different tabs using the arrow keys. The focus moves back off the tab-control when users click on some other object on the dialog.
If the value is nil, the keyboard focus will not move from wherever it just was when users click on the tab-control.
The focus-on-click property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :focus-on-click initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
focus-on-click is a property of the tab-control class.
Generic Function, cg package
Arguments: grid-widget
Returns the row-section of grid-widget (a grid-widget) that either has or most recently had the keyboard focus, or else nil if grid-widget has not yet had the keyboard focus.
This is the row-section that will get the keyboard focus the next time the grid-widget itself gets the keyboard focus.
Generic Function, cg package
Arguments: grid-section
Returns the grid-subsection of grid-section (a grid-section) that either has or most recently had the keyboard focus, or else nil if grid-section has not yet had the keyboard focus.
This is the grid-subsection that will get the keyboard focus the next time grid-section gets the keyboard focus.
See grid-widget for a general discussion of grid-widgets, of which grid-sections nd grid-subsections are parts.)
Generic Function, cg package
Arguments: outline
Returns the outline-item within outline (which should be an instance of the outline class) that currently has the keyboard focus (or would have if the outline itself had it). This item is drawn with a dotted rectangle around it when the outline has the focus. It is usually the same as the selected-outline-item, but not when scrolling with the keyboard has moved the focus to an item that is in view without changing the selected item.
See also focus-index, select-outline-item, and selected-outline-item.
Generic Function, cg package
Arguments: object
Returns the current value of the font property of object. This determines the font that's used whenever text is displayed on the object, which may be a window, a widget, or a part of a widget.
The font of a stream can be set initially by passing a font keyword argument when creating the object, and/or changed later at any time by calling (setf font) or by using the macro with-font. A font is first created by calling make-font-ex or ask-user-for-font.
font is a property of graphical-stream, which includes all windows as well as bitmap-streams and printer streams. (An exception is that it is not applicable to menus, because a single font is used globally for all menus.) It is also a property of dialog-item, where it is applicable to any widget that draws text, and a property of certain widget parts, such as outline-item and grid-column.
Setting the font of a graphical-stream affects text that will be drawn on the stream later by calling CG functions as draw-string-in-box or general Lisp printing functions such as princ. Setting the font of a widget or a widget part affects text that is already displayed in the widget, or which will be put into the widget later by setting its value.
The setf function can take an additional optional argument called set-line-height-too. If this argument is true, then (setf font) will also set the current line-height of the object to be equal to the font-height of the new font. This is typically desirable so that printing a newline to the stream will position the next line of text appropriately, so this argument defaults to t. The default could be overridden, though, with a form such as (setf (font my-window nil)(make-font-ex nil "Arial" 18)).
Function, cg package
Arguments: font
Returns the angle of the specified font, which must be a font as created with make-font-ex, make-font, or ask-user-for-font. The value is an integer indicating degrees counterclockwise from the usual horizontal angle at which all strings that are drawn in the font will be drawn. The default is zero.
Function, cg package
Arguments: fontmetrics
Returns the maximum height of a character from the baseline for the fontmetrics structure specified by the argument. This height measured in stream units of the stream associated with the argument, which must be a fontmetrics object.
There are font methods for the graphical-stream class (formerly called windows-graphics) and subclasses of it, for various dialog-item classes that display text, and for grid-subsection and outline-item.
The setf of this function may be called to set the current font of the object. The setf takes an additional optional argument called set-line-height-too. This is used only when the object is a graphical-stream (which includes windows and other objects on which drawing may be done). When true, the line-height of the stream is set to the font-height of the font. The default value is t; this is usually the appropriate value, so that newlines printed to the stream will advance the current y position as appropriate for this font. Therefore a font is typically set with a form such as this:
(setf (font my-window) (make-font-ex nil "Arial" 18))though to avoid changing the window's line-height you could instead use this:
(setf (font my-window nil)(make-font-ex nil "Arial" 18))The font of an object may also be set by passing a :font initarg when creating the object, and by calling with-font.
Regarding outline-items: while the font of an individual outline-item may be set, all of the items in the outline will retain the same height, which is the font-height of the font of the outline. For this reason, the font of an outline-item should not be taller than the general font of the outline, or else the text will be clipped.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the average character width of the font associated with the fontmetrics specified by the argument.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the maximum extent of any character below the baseline for the font associated with the fontmetrics specified by the argument.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns true if the specified fontmetrics object is a "device" font (a Microsoft Windows concept).
This function is meaningful only on the Windows platform. The value will always be nil on other platforms.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the direction (one of :left-right, :right-left, :top-bottom, :bottom-top) for the font associated with the fontmetrics specified by the argument.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fonta fontb
Returns true if fonts a and b are equal. If the family field (which typically has no effect) of one font is set and of the other font is nil, this function returns true. (The family field sometimes gets filled in and sometimes does not get filled in.)
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the external leading of the fontmetrics object specified by the argument.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the face of the argument, which must be a font object.
See also Text and Fonts in cg-drawing.html.
Generic Function, cg package
Arguments: font-face
Returns whether the specified font face names a fixed-width font, which is one where all characters have the same width.
font-face should be a string that names a font face. It should be one of the strings that are returned by the function font-faces, and which can be passed as the face argument to make-font-ex.
This function may be more convenient than font-fixed-width-p.
Generic Function, cg package
Arguments: screen
Returns a list of all font faces that are available on the end user's system. Each member of the list is a string that could be passed as the value of the face argument to make-font-ex, make-font, or font-sizes.
The argument should be the screen, which is returned by the expression (screen *system*). See screen and *system*.
Function, cg package
Arguments: fontmetrics
Returns the family of the argument, which must be a font object.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns true if all of the characters of the specified font have the same width.
fontmetrics must be a fontmetrics object.
A more convenient function to use is font-face-fixed-width-p, which works directly on a font face name. The fontmetrics accessor functions like this one, on the other hand, require assigning a font to a window and then calling fontmetrics to retrieve that window's fontmetrics object. This function may be more efficient, though, if the font is already assigned to a window.
See also Text and Fonts in cg-drawing.html.
Generic Function, cg package
Arguments: stream
Returns a handle to the current font of stream. Such a handle can be more efficiently used by (setf font) on this stream. It is not specified what type of object this is.
Function, cg package
Arguments: fontmetrics
Returns the height of the argument, which must be a fontmetrics object.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the internal leading of the argument, which must be a fontmetrics object.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the leading of the argument, which must be a fontmetrics object.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: font
Returns the line-height of the argument.
Function, cg package
Arguments: fontmetrics
Returns the maximum character width of the argument, which must be a fontmetrics object.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: font
This function is not useful, because it simply returns what font-size returns. It had different behavior on the GTK version of CG, which is no longer supported.
Generic Function, cg package
Arguments: grid-column
Returns a function that returns the font to use when drawing each grid cell of a a particular column, or else returns nil to determine the font in other ways. This function is called by the default cell-font method, which in turn is typically called by a draw-cell method (including those supplied by editable-text-column-mixin and other mixins). A font-reader may be nil rather than a function if this facility is not used. The default value is nil.
The font-reader function is a property of a particular grid-column, and is called once for each grid-row that intersects that column, to determine the font of the cell at the intersection of that row and column. The function should take one argument, which is the data-object of the grid-row. If the font for a particular cell should be determined by the font-reader function, then it should return the font to use, and otherwise it should return nil.
This property value may be specified as either a function name symbol (which would be more debuggable), or a function object (which may be slightly faster, though probably insignificantly), or nil.
An application does not call the font-reader function; it supplies the font-reader function by calling (setf font-reader) or by passing the :font-reader initarg when calling make-instance to create a grid-column, and the specified function is then called automatically by the system as needed.
See the grid-widget class for an overview of writing grid-widget code.
Function, cg package
Arguments: fontmetrics
Returns the size of the argument, which must be a font object. This is the official pixel height that was requested when calling make-font-ex or make-font. It is generally better to call font-line-height to find the real height of a line of text that is drawn in this font on a stream, including the blank space (leading) that is added when a newline is printed.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns true if the size of the font associated with the argument, which must be a fontmetrics object, is the same as the character height.
See also Text and Fonts in cg-drawing.html.
Generic Function, cg package
Arguments: stream face
Returns a list of the available font sizes for a particular stream and font face. stream should be an instance of the graphical-stream class, and face should be one of the strings that are returned by font-faces. The result may or may not depend on the particular stream.
When the face names a font that can scale to any size, such as a TrueType font in Windows, then the returned list will contain zero as its only element. Otherwise the list will contain pixel sizes that could be passed as the size argument to make-font-ex or make-font. The sizes will be sorted from smallest to largest.
(If some other size is passed to make-font-ex or make-font, the function will find the nearest available size.)
Function, cg package
Arguments: font string &optional start end
Returns the width in font of the substring of string starting at start and ending at end (the whole string if start and end are not specified).
start must be greater than or equal to 0 and less than or equal to end, which must be greater than or equal to 0 and less than or equal to the length of string.
Example (the return values depend on the font returned by system-font; you may see different values):
(font-string-width (system-font) "foo") -> 20
(font-string-width (system-font) "foo" 0 3) -> 20
(font-string-width (system-font) "foo" 1 3) -> 16
(font-string-width (system-font) "foo" 2 2) -> 0
(font-string-width (system-font) "foo" 0 4) -> ERROR (The last example errors because end is larger than the length of string.)
Function, cg package
Arguments: font
Returns the style of the argument, which must be a font object.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns the style word of the argument, which must be a font object. To the device manager, the font style is represented as a fixnum (the style word). Each bit indicates a particular style:
Style :bold has weight 1.
Style :italic has weight 2.
Style :underline has weight 4.
Style :condensed has weight 32.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns true if the specified fontmetrics object is for a truetype font, and returns nil otherwise.
This function is meaningful only on the Windows platform. The value will always be nil on other platforms.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: fontmetrics
Returns true if the characters of the specified fontmetrics object are rendered with line-drawing techniques rather than with pixel map techniques. This is true of all truetype fonts, and can also be true of non-truetype fonts such as postscript fonts. This function returns nil if the characters are rendered with pixel map techniques.
This function is meaningful only on the Windows platform. The value will always be nil on other platforms.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: stream
Returns a fontmetrics object describing the current font of stream.
A fontmetrics object must be passed to several functions that return font attributes, such as font-leading and font-fixed-width-p. The destructive version of this function is nfontmetrics.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: object
Returns true if object is an instance of the font class and returns nil otherwise.
Generic Function, cg package
Arguments: grid-widget
This is like body-column-count, except for a column-section named :footer.
If (setf footer-column-count) creates the section, it will always be added as the last section. And (unlike body-column-count) if the new number is zero, then the section will be removed entirely.
See body-column-count for more information as the operators are similar except as noted.
Generic Function, cg package
Arguments: grid-widget
Like body-column-defaults, except for a column-section named :footer. See that page for details.
Generic Function, cg package
Arguments: grid-widget
This is like body-columns, except for a column-section named :footer rather than :body. See that page and make the appropriate substitutions, as that makes clear the functionality is essentially the same.
Generic Function, cg package
Arguments: grid-widget
This is like body-row-count, except for a row-section named :footer.
If (setf footer-row-count) creates the section, it will always be added as the last section. And (unlike body-row-count) if the new number is zero, then the section will be removed entirely.
See body-row-count for more information as the operators are similar except as noted.
Generic Function, cg package
Arguments: grid-widget
Like body-row-defaults, except for a row-section named :footer. See that page for details.
Generic Function, cg package
Arguments: grid-widget
This is like body-rows, except for a row-section named :footer rather than :body. See that page and make the appropriate substitutions, as that makes clear the functionality is essentially the same.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the footnote property of a chart-or-plot. The value may be set at creation time by passing the :footnote initarg, or any time later by calling (setf footnote).
A string to display below a chart-or-plot's body (but above the legend if any), or else nil to avoid drawing a footnote. The string will be drawn using the footnote-color and footnote-font of the chart-or-plot. The default value is nil.
The string will be wrapped at spaces if it does not fit on one line, and space is allocated automatically to accomodate the number of lines that are required. The string may also contain embedded newline characters to explicitly wrap the text at particular places.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the footnote-color property of a chart-or-plot. The value may be set at creation time by passing the :footnote-color initarg, or any time later by calling (setf footnote-color).
The color that is used to draw the footnote of a chart-or-plot, if any. The value should be an RGB object (see make-rgb). The default value is the value of black.
See footnote.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the footnote-font property of a chart-or-plot. The value may be set at creation time by passing the :footnote-font initarg, or any time later by calling (setf footnote-font).
The font that is used to draw the footnote of a chart-or-plot, if any. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 12).
See footnote.
See chart-widget and also .
Generic Function, cg package
Arguments: standard-object
Returns the foreground color for standard-object if one has been specified for it, and otherwise returns nil. (By contrast, effective-foreground-color will always return a color, by calling default-foreground-color when foreground-color returns nil.)
The foreground-color is the color in which graphics will be drawn and text will be written on the argument object, by calling functions such as draw-line, fill-box, draw-string-in-box, or print. By contrast, background-color is the color used to "erase" the object's drawing area. foreground-color and background-color apply to windows, dialog-items, button-infos (of a multi-picture-button), and outline-items (of an outline).
A foreground color may be specified either by calling (setf foreground-color) or by passing the foreground-color initarg to make-instance or make-window when creating the object. The value may be either an RGB instance (see make-rgb) or nil. nil means to use the default-foreground-color for the object. (In particular, the value cannot be an HLS color, as returned by make-hls. If you use HLS colors, apply hls-to-rgb to them before setting this property, and call rgb-to-hls to get the HLS equivalent of an RGB value.)
It is typical to leave the foreground-color of an object nil. In that case, the default-foreground-color is used. If the initial method of that generic function is used, default-foreground-color will return a system color such as the one returned by system-foreground-color. This causes your application to use the end user's preferred colors that they have selected in the Windows Control Panel.
When the foreground-color is an RGB color, the actual RGB instance that is passed to (setf foreground-color) is retained to be returned later by foreground-color. Therefore, applications should not modify an RGB instance while it is assigned to an object. A single RGB instance may be assigned to any number of objects, however.
In earlier releases, this generic function had an optional argument, result-rgb, which was already deprecated and unused. Starting in release 7.0, that argument is no longer supported. Code which includes that argument will signal an error. The error can be fixed by removing any reference to a second, optional argument.
See also with-foreground-color, a convenient macro that temporarily changes the foreground color while a body of code is executed. See also background-color.
Function, cg package
Arguments:
The functionality described here is what happens when running in Windows desktop mode. When running in CG/JS mode, this function simply calls selected-window on the screen.
This function returns the currently selected top-level window in this Lisp if this Lisp is the currently selected application, and otherwise returns nil. Returns the window even if it is in another thread of the same Lisp.
This function may be useful for determining whether this Lisp (either a development environment or standalone application) is the application that is currently selected by the user, by simply checking whether the return value is true.
Note that the expression
(selected-window (screen *system*))differs in that it will return the most recently selected top-level even when this Lisp is not the currently selected application. (See selected-window.)
See also set-foreground-window.
Generic Function, cg package
Arguments: module
Returns the form window associated with the specified project module. form is a property of the form-module class.
Generic Function, cg package
Arguments: window
Returns true if window is an instance of the form class; returns nil otherwise.
Generic Function, cg package
Arguments: window
If window is a frame-with-single-child and its single child pane is still open, returns that pane; otherwise returns nil.
Function, cg package
Arguments: window
Returns true if window is the single child of a frame-with-single-child window; otherwise returns nil.
Function, cg package
Arguments: window-or-screen
Returns the first ancestor of window that is either a frame-window or the screen.
Function, cg package
Arguments: object
Returns true if object is an instance of the frame-window class; returns nil otherwise.
Generic Function, cg package
Arguments: window
This function is no longer used. It was related to the GTK version of CG, which is no longer supported.
Generic Function, cg package
Arguments: parent-stream &key owned-p states for-focus
parent-stream may be either a window or the screen.
If owned-p is nil (the default), returns the frontmost child window of parent-stream, if any, and otherwise returns nil.
If owned-p is true, returns the frontmost owned window of parent-stream that is not also a child window of parent-stream, if any, and otherwise returns nil.
If states is non-nil, then it should be a list of window state symbols, and windows whose state is not in this list are skipped. If nil (the default), then these windows are not skipped. Valid symbols for this list are :normal, :shrunk, :icon, and :maximized. See state.
If for-focus is true, then windows whose events are currently disabled (see enable-events) are skipped, and "static" control windows are skipped as well. ("Static" control windows include static-text-pane, static-picture-pane, and group-box-pane.) If nil (the default), then these windows are not skipped. Such windows do not handle any keyboard events, so passing this argument as true may be useful for finding a window to move the keyboard focus to by calling set-focus.
See also next-window and windows.
Generic Function, cg package
Arguments: list-view
This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.
Returns the value of the full-row-select property of a list-view control. The value may be set at creation time by passing the :full-row-select initarg to make-instance, or any time later by calling (setf full-row-select).
This property specifies whether the entire row (rather than the left column only) for a selected list-view value is highlighted and clickable. The value can be nil or true. The default is nil.
Generic Function, cg package
Arguments: menu menu-item window-or-screen
Funcalls the value of the menu-item with no arguments. funcall-menu-item could be defined as:
(defun funcall-menu-item (menu menu-item window-or-screen)
(funcall (value menu-item)))This function and funcall-menu-item-with-window are typical values of the on-click property of a menu.
Function, cg package
Arguments: menu menu-item stream
This function is suitable as the on-click function for menu-bars on a rich-edit-dialog or other dialog that contains a rich-edit widget. It acts just like funcall-menu-item-with-window, except that it calls find-rich-edit-pane on stream to find the argument to pass to the menu-item's function, rather than passing stream itself.
Generic Function, cg package
Arguments: menu menu-item window-or-screen
Funcalls the value of the menu-item with the window on which the menu was invoked (window-or-screen) as the single argument. If the window is a frame-with-single-child window, then the child pane is passed instead. Here is the definition of funcall-menu-item-with-window:
(defmethod funcall-menu-item-with-window
((menu menu)(menu-item menu-item) window-or-screen)
(funcall (value menu-item)
(or (frame-child stream) window-or-screen)))This function and funcall-menu-item are typical values of the on-click property of a menu. On rich-edit-dialogs, funcall-menu-item-with-rich-edit may also be used.
Generic Function, cg package
Arguments: multi-picture-button
Returns (or sets with setf) the value of the gap-size property of a multi-picture-button control. This value is the extra pixel-width that is allotted for a gap between certain buttons of a multi-picture-button. (A gap appears wherever the keyword symbol :gap is included within the list of button-info objects in the multi-picture-button's range.)
The default value is 8. The value of the spacing property, which determines the general spacing between buttons, is added to the gap-size to find the total spacing between two buttons that have a gap between them.
A separator bar (a vertical line) is also drawn when the value of the multi-picture-button control's button-3d-border property is :when-pressed. If a separator bar is drawn in the gap, it is drawn in the middle of the gap area.
Function, cg package
Arguments: pixmap transparent-pixel-value
Automatically creates a mask for pixmap that causes the pixmap to be transparent wherever transparent-pixel-value occurred in the pixmap's contents. The created mask texture is returned, and is set to be the mask property of the pixmap.
pixmap should be the pixmap to be given a mask. See cg-pixmaps.html for an overview of pixmap functionality.
transparent-pixel-value should be a non-negative integer or nil. Any pixel in the contents of the pixmap that has this value will become transparent. This is done by setting the mask's pixel value to one and the main image's pixel value to zero, just as you would need to do if you constructed the pixmap's mask-contents yourself.
If transparent-pixel-value is not zero, this means that the existing main texture of the pixmap will be modified by this function. In any case, the pixmap will be given a new mask, and any mask that the pixmap had will be removed from the pixmap.
If the transparent-pixel-value argument is nil, the value of the upper-left pixel of the pixmap is taken as the value to make transparent.
Function, cg package
Arguments: start-name &key hyphenate package
Creates and returns a unique symbol in the specified package, based on the printed representation of start-name. This is useful for generating unique symbol names for objects.
Basically, gensym-sequential-name takes the print name of start-name, removes any numerals and hyphens from the end, optionally appends a hyphen, appends the string representation of the lowest positive integer that has not yet been used with the print name of start-name and that causes the completed string to not name an existing symbol after the string's case has been changed as appropriate for the *current-case-mode*, interns the string in the specified package, and returns the resulting symbol.
start-name may be any object, but is typically a symbol (which may have been created by gensym-sequential-name as well) or a string.
If hyphenate is specified, then a hyphen is appended before the number if and only if hyphenate is true. If hyphenate is not specified, then a hyphen is appended if and only if there are any other hyphens in the base string (after all numerals and hyphens have been removed from the end).
package may be either a package object or the name of a package. The default value is :keyword.
Examples (in a fresh Lisp):
(gensym-sequential-name 'foo) returns :foo1
(gensym-sequential-name 'foo) returns :foo2
(gensym-sequential-name :foo1) returns :foo3
(gensym-sequential-name :foo-bar) returns :foo-bar-1
(gensym-sequential-name :foo-bar-1) returns :foo-bar-2
(gensym-sequential-name :baz :hyphenate t) returns :baz-1
(gensym-sequential-name :baz :hyphenate t :package 'common-lisp-user)
returns common-lisp-user::baz-2Generic Function, cg package
Arguments: window &key include-ancestors
Returns a plist that indicates whether each capability of the gesture interface is enabled for the specified window. Each key in the plist is a keyword symbol that corresponds to one of the arguments to configure-gestures. Each value is either t if the capability has been explicitly enabled by a call to configure-gestures, nil if it has been explicitly disabled, or :inherit if the value is inherited from an ancestor window or else from system defaults.
If include-ancestors is true, then Microsoft says that it "returns consolidated configuration for the specified window and its parent window chain". This appears to mean that if :inherit would otherwise be returned for a value, but there is an ancestor window for which the capability has been explitly enabled or disabled, then t or nil is returned to indicate the inherited behavior. But :inherit will still be returned if the unknown system default is inherited.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: window target gesture x y distance beginning ending inertia
This generic function is called one or more times for any touchscreen gesture on a window, unless register-touch-window has been called to switch that window to the touch interface (in which case touch-event will be called instead). This function will be called once for each different position of one or more fingers during the gesture. This is the somewhat higher-level interface that figures out which type of gesture is being done for you, though only five standard gestures are supported.
An application can supply methods for this generic function to handle gestures. If a method handles a gesture, it should return true. Otherwise it should return nil to pass the event up to the parent window if any, or else to perform the default behavior that's built into Windows. The default method on basic-pane does nothing and returns nil.
window is the window to which Windows is sending an event, while target is the window where the current gesture began (even if the user has dragged out of that window). Initially these will be the same window. But if the method returns nil and there is a parent window, then gesture-event will be called again where window is the parent window while target is still the window where the gesture began. Similarly, if the method for that window returns nil then gesture-event will be called yet again where window is the grandparent window (if there is one), while target is still the same target window.
This design could be used, for example, by defining a method that specializes the window parameter on a dialog subclass. If the user touches a widget on that dialog and drags across the dialog, then each position during the drag would first call gesture-event with window and target being the widget-window, in which case the default method will return nil, causing gesture-event to be called again where window is the dialog. You could then handle the gesture in your method that specializes on the dialog, even though the user intially touched a child widget.
x and y are the coordinates of the current center position of the one or more fingers that are currently on the screen, measured in pixels. These are stream coordinates of window, which means relative to the upper left corner of the canvas that is being scrolled in window if it scrolls, or else relative to the upper left of the interior of window.
gesture is a keyword that indicates which of the several standard high-level gestures is being performed. This is one of :pan, :zoom, :rotate, :two-finger-tap, or :press-and-tap. Here are their meanings:
:pan - one or two fingers are being dragged, typically to scroll the window
:zoom - two fingers are either moving closer to each other or farther apart (a pinch or a spread)
:rotate - two fingers are moving in a circular manner around a central point
:two-finger-tap - two fingers touched the screen and were removed without dragging
:press-and-tap - one finger touched the screen and then another touched the screen while the first was still down
distance is the distance between the two fingers, measured in pixels. This will be zero if only one finger is touching the screen. For a :rotate gesture, this is instead an angle measured in radians, referring to the angle of a line that goes through both finger positions.
beginning is true if this is the first call to gesture-event for this gesture, and nil otherwise. The first call is made for the first finger that touches the screen, though only after a partial drag indicates which type of gesture is being performed.
ending is true if this is the last call to gesture-event for this gesture, and nil otherwise. The last call is made when the last finger stops touching the screen (or the last inertia event comes in after all fingers have left the screen).
inertia is true if this call results from inertia after all fingers have left the screen, and nil otherwise. This applies only to the :pan gesture, and will always be nil for other gestures. If inertia is enabled for this window (see configure-gestures), and all fingers leave the screen during a drag, then calls will continue to be made to gesture-event for a brief period, as if the user had continued to drag until gradually coming to a halt. An application typically can simply ignore the fact that no fingers are still on the screen and scroll the window according to the changing x and y values as usual, and then the scrolling will come to a gradual halt after the user makes a fling gesture.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html, where there is a complete example.
Function, cg package
Arguments: window-or-screen &optional scroll-p cursor first-corner
Waits for the user to press a mouse button down, then waits for the mouse button to be released, and then returns a box that has two corners at the mouse cursor positions of the button press and the button release. Between the button press and the button release, a rubber-band box is drawn between the button press position and the current mouse cursor position.
If first-corner is true, then it should be a position object (see make-position). It will then be used for the button-down position rather than waiting for the user to press a mouse button. In this case, either a button press or release will mark the second corner.
The other arguments work the same as in get-line.
You may wish to call wait-for-mouse-buttons-up prior to calling get-box to ensure that mouse button releases associated with other actions do not interfere with getting the desired box.
See also get-screen-box and nget-box.
Generic Function, cg package
Arguments: window &key (scope :selection)
This function is specific to Windows desktop mode and should not be called in CG/JS mode.
Depending on the value of the scope keyword argument, returns the default format of the window or the format of the first character of the selected text.
window must be an instance of a text-edit-pane (a rich-edit-pane is such an instance). Note that neither a text-edit-window, typically the parent of a text-edit-pane, or a rich-edit control are acceptable arguments, though the result of applying window to a rich-edit control is acceptable.
scope is either :default or :selection, and controls the returned value. If it is :selection, then details of the format of the first character of the currently selected text are returned. If it is :default, then details of the default character formatting for the window are returned.
The formatting details are returned as multiple values. The "same-foo" values shown here are valid only when scope is :selection. Here are the returned values in order:
face: the keyword symbol for the font face
bold: true if the character is bold
italic: true if the character is italic
underline: true if the character is underlined
height: the point-size of the font of the character
color: the rgb color of the character (see make-rgb)
same-face: true if the whole selection is the same face (returned value has no meaning when scope is :default)
same-bold: true if the whole selection is either all bold or all non-bold (returned value has no meaning when scope is :default)
same-italic: true if the whole selection is either all italic or all non-italic (returned value has no meaning when scope is :default)
same-underline: true if the whole selection is either all underlined or all non-underlined (returned value has no meaning when scope is :default)
same-height: true if the whole selection is the same height (returned value has no meaning when scope is :default)
same-color: true if the whole selection is the same color (returned value has no meaning when scope is :default)
character-format returns a character-format object which encapsulates the information returned by get-character-format.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: window-or-screen box &optional scroll-p cursor
Waits for the user to press or unpress a mouse-button, and then returns the coordinates of a box that has been drawn continuously to follow mouse movement during the wait, beginning at box. The width and height of the box remain the same while dragging the box along with the mouse.
box must be a box object, as created by make-box or allocated by with-boxes.
The other arguments work the same as in get-line.
You may wish to call wait-for-mouse-buttons-up prior to calling get-fixed-box to ensure that mouse button releases associated with other actions do not interfere with getting the desired box.
See also nget-fixed-box and get-box.
Generic Function, cg package
Arguments: &optional ignored
Returns the window that currently has the global keyboard focus, if any, or else nil. The window that has the keyboard focus at any moment is the one that will receive all keyboard events. The focus is usually indicated visually in some way, such as by a dashed bounding rectangle or inverted text. The focus may be moved to another window by calling set-focus. It is possible for no window to have the focus.
The keyboard focus is normally in a window that has no child windows, since parent windows tend to move the focus to one of their child windows. When a dialog is selected, for example, the dialog's toolbar will be highlighted to indicate that it is the selected-window, but the keyboard focus will be in the window of one of the widgets on the dialog.
get-focus is thread-specific. If the focus is currently in a window that was created by the thread that is calling get-focus, or if there is a window hierarchy that contains windows from both the calling thread and window's creation thread, then that window is returned. Otherwise nil is returned. (set-focus, on the other hand, will move the focus to a window in any thread of that Lisp environment.) Note that mixing windows from multiple threads in a single window hierarchy is not recommended, since this is prone to messaging deadlocks.
Compatibility note: The optional argument is called ignored because it is ignored. In releases through version 6.0 it was documented as optionally specifying a parent stream but in fact it was always ignored since the keyboard focus is global. The argument is accepted for backward compatibility and since the argument was always in fact ignored, no behavior is changed if you specify any value or do not specify a value.
See also selected-window.
Function, cg package
Arguments: window-or-screen start-position &optional scroll-p (cursor t)
Waits until the user presses or releases a mouse button, and then returns the mouse cursor-position in the stream coordinates of window-or-screen.
During the wait, a rubber-band line is continuously drawn between start-position and the current mouse position.
You can bind the variable *opaque-rubber-banding* to t around calls to this function to draw in a newer and nicer style than the traditional XORing, though it may be slower.
window-or-screen should be a basic-pane or the screen.
start-position should be a position in the stream coordinates of window-or-screen.
If scroll-p is true and window-or-screen is a window, then the window will be scrolled if the mouse cursor moves outside of the window's interior.
The mouse cursor image will be set to cursor, where a value of t (the default) means to use the cross-cursor.
Related function for other kinds of drags include get-box, get-fixed-box, get-shape-line, get-shape-box, and get-shape-fixed-box. Alternate functions like nget-line that begin with nget- simply avoid consing a position or box object, which is not significant.
Generic Function, cg package
Arguments: window
This function is specific to Windows desktop mode and should not be called in CG/JS mode.
Returns the paragraph formatting of the selected text. All paragraphs that are at least partly in the selected text are considered to be selected.
window is a text-edit-pane and is typically a rich-edit-pane (a subclass of text-edit-pane). Note that neither a text-edit-window (typically the parent of a text-edit-pane) nor a rich-edit control are valid arguments to this function. Applying window to a rich-edit control results in a suitable argument, however.
Twelve multiple values are returned:
justification: either :left, :center, or :right
numbering-style: either :plain or :bullets
top-left-indentation: a number in points
body-left-indentation: a number in points
right-indentation: a number in points
tabs: a list of tabstops in points
same-alignment: true if all paragraphs have the same alignment
same-numbering-style: true if all paragraphs have the same numbering style
same-top-left-indentation: true if all paragraphs have the same top left indentation
same-body-left-indentation: true if all paragraphs have the same body left indentation
same-right-indentation: true if all paragraphs have the same right indentation
same-tabs: true if all paragraphs have the same list of tabstops
See set-paragraph-format.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: common-status-bar &key (part 0)
Returns the string currently displayed in the specified part of the specified common-status-bar. Similar to the function get-text for most windows, but with the additional part argument. part defaults to zero to indicate the leftmost part (or the only part when there is a single part).
If a non-existent part index is specified, or if the empty string is currently displayed in the part, then nil is returned rather than a string.
Generic Function, cg package
Arguments: stream-or-texture-handle &optional from-box texture texture-info
This function has been renamed get-texture. The get-pixels symbol has been maintained for backward compatibility. See get-texture for a description.
See also get-pixmap, which provides a better interface to achieving what get-texture does.
Generic Function, cg package
Arguments: stream &key box
Creates and returns a pixmap that is a copy of the image that is currently displayed in the specified rectangular area. The stream should be a window, or alternately the screen when running in Window mode. If box is nil, then the entire interior of stream is copied; otherwise box should be a box (see make-box) that specifies a portion of the page (scrollable canvas) of stream, to indicate the area of the window or screen to copy. When stream is the screen, the box argument must be specified.
get-pixmap is functionally equivalent to the older function get-texture, except that it returns the higher-level pixmap object rather than separate texture and texture-info objects, and the optional texture and texture-info parameters are not present on get-pixmap (to avoid consing these arguments).
See also get-screen-pixmap.
When running in Windows desktop mode, the image that's copied is whatever appears on the screen at that moment. If other windows are covering stream, then whatever covers the specified area of stream is what is copied. Therefore, when passing a window (rather than the screen) to get-pixmap, an application typically will first ensure that the window being copied is not covered by other windows, and that the desired part of the window's page is currently scrolled into the window.
An exception to the above is that if stream is a bitmap-pane, then the image is copied from the memory bitmap of the bitmap-pane rather than from the screen. If box is nil, then the entire page of the bitmap-pane is copied; otherwise box should specify the portion of the bitmap-pane's page to copy. (The bitmap-pane of a bitmap-window may be found by calling frame-child on the bitmap-window.)
Another exception is that if the double-buffered property of a window is true, then get-pixmap will return an image from the window even if the window is covered, but only for the part of the window's page that is currently scrolled into the window's interior (see visible-box). The reason is that a double-buffered window has a memory bitmap, but only for the interior area of the window.
Function, cg package
Arguments: window-or-screen &optional scroll-p cursor
Waits until the user presses a mouse button down, and then returns the current cursor-position of the mouse cursor in the stream coordinates of window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*.
The arguments work as described under get-line.
You may wish to call wait-for-mouse-buttons-up prior to calling get-position to ensure that mouse button releases associated with other actions do not interfere with getting the desired position.
Function, cg package
Arguments: &key prompt title no-dialog no-draw
Waits for the user to specify two corner positions on the screen, and returns a box made from those positions. To allow the specification of any screen positions without affecting whatever windows are at those positions (as might happen with a mouse click), the user must specify each position by placing the mouse cursor at the desired position and then pressing the Control key.
If no-dialog is nil then a modal dialog first appears to explain the specification procedure to the user; if no-dialog is true then the dialog is skipped. If prompt is nil, then a general explanation appears in the dialog; otherwise prompt should be a similar string that may be customized to the particular application. title is either a string to serve as the title of the modal dialog or nil (the default) for no title.
If no-draw is nil (the default), then a rubber-banding box is drawn during the time between the two presses of the Control key to indicate the region that is being selected. If no-draw is true, then this box is not drawn. Drawing the box could leave screen droppings if the area being copied is being updated as the user is specifying the box.
The return value is a box (see the box class) unless the user presses the Escape key to cancel the interactive specification of the box, in which case nil is returned.
Function, cg package
Arguments: &key box prompt title no-dialog no-draw
This function simply calls get-pixmap to create a pixmap from the image in an area of the screen, first calling get-screen-box if box is unsupplied. The box argument is passed to get-pixmap, while the other arguments are passed to get-screen-box.
If no-draw is nil (the default), then a rubber-banding box is drawn during the time between the two presses of the Control key to indicate the region that is being selected. If no-draw is true, then this box is not drawn. Drawing the box could leave screen droppings if the area being copied is being updated as the user is specifying the box.
The return value is a pixmap unless box is nil and the user presses the Escape key to cancel the interactive specification of the box, in which case nil is returned.
Generic Function, cg package
Arguments: stream
This function returns two numeric values indicating the start and end positions of the currently selected text of the control identified by stream, which must be a text control of some sort or a text-edit-window or text-edit-pane.
If there is no text selected, then the two returned values are equal and indicate the current text cursor position; zero indicates the beginning of the text.
See also set-selection, selected-object, selected-string, and selected-symbol. Those functions may return true when no text is highlighted (they can return the text surrounding the text cursor as well as highlighted text). Menu command such as Cut only work on highlighted text, while, in the IDE, others, such as Copy, work on the text surrounded the cursor if no text is highlighted (the IDE differs from Common Windows practice in this regard). get-selection can be used, either alone or in conjunction with those functions, to determine whether menu-items that work on selected or highlighted text should be made unavailable. See about-to-show-menu, which is called prior to a menu being displayed.
Function, cg package
Arguments: window-or-screen draw-fn erase-fn &optional scroll-p cursor first-corner
This is similar to get-box, except that draw-fn is called each time the shape is to be drawn and erase-fn each time it is to be erased. draw-fn and erase-fn must be functions (function objects or function names, typically symbols) that accept two arguments: the window-or-screen and the current box. When they are called, the stream's brush will be set to one pixel-width black, and the stream's paint-operation will be set to po-xor. Thus, drawing the shape twice will suffice to also erase it at each step.
The other arguments works as in get-line.
(get-box s) is equivalent to (get-shape-box s #'draw-box #'draw-box).
Note that the resulting box may be destructively modified later by the system, so if you want to keep it around then you should make a copy of it.
See also nget-shape-box.
Function, cg package
Arguments: window-or-screen box draw-fn erase-fn &optional scroll-p cursor
This is similar to get-fixed-box, except that draw-fn is called each time the shape is to be drawn and erase-fn each time it is to be erased.
The draw-fn and erase-fn arguments work as in get-shape-box. The other arguments work as in get-line.
(get-fixed-box s box) is equivalent to (get-shape-fixed-box s box #'draw-box #'draw-box).
Note that the resulting box may be destructively modified later by the system, so if you want to keep it around, you should make a copy of it with copy-box.
See also nget-shape-fixed-box.
Function, cg package
Arguments: window-or-screen start-position draw-fn erase-fn &optional scroll-p cursor
Performs a "rubber band" operation where the user drags a stretching line that is drawn on stream between start-position and the current mouse cursor-position. If the function draw-line is passed as the draw-fn and erase-fn, then get-shape-line will act just like get-line and do a simple rubber-banding. If a fancier sort of rubber-band line is desired, then custom functions can be passed in instead. The draw-fn and erase-fn functions should each take three arguments: the window-or-screen, the start-position, and the current mouse-cursor position.
You can bind the variable *opaque-rubber-banding* to t around calls to this function to draw in a newer and nicer style than the traditional XORing, though it may be slower. And this style may not work at all, depending on how the custom draw-fn and erase-fn are written.
window-or-screen should be a basic-pane or the screen.
If scroll-p is true and window-or-screen is a window, then the window will be scrolled if the mouse cursor moves outside of the window's interior.
The mouse cursor image will be set to cursor, where a value of t (the default) means to use the cross-cursor.
See also nget-shape-line.
Function, cg package
Arguments: simple-stream indicator &optional default
This function is intended for use in device and location managers and may only be applied to simple streams. It returns user-definable stream properties which are stored on the stream plist.
Commonly used stream data values are stored in special fields in streams. It is unlikely that the user-defined stream properties will need to be used.
Generic Function, cg package
Arguments: window-or-widget &key return-crlf
Returns as a string the text of a window or dialog-item. For a text control (such as an editable-text control or a multi-line-editable-text control) or a text-edit-pane, the returned text is the contents of the control or pane, while for other windows the title is returned. Note that for a text control, the returned text will always be the actual text that is presently displayed in the control, even if the user has just typed it in and the value of the dialog-item has not yet been updated to reflect the new text because the control still has the keyboard focus.
The return-crlf argument no longer has any effect, and is kept for backward compatibility only. It was used on the Windows platform by an earlier version of the RichEdit control.
The length of the returned string is returned as a second value.
See also set-text, which can be used to set the text in a text-edit-pane.
Generic Function, cg package
Arguments: text-edit-pane
This generic function is implemented only on Windows.
Returns the current zoom ratio of a text-edit-pane or rich-edit-pane. The returned value will be a rational number (an integer or ratio) between 1/64 and 64, inclusive. It will be 1 unless set-text-zoom has been called to change it, or perhaps if something like a special mouse wheel driver has changed it.
Generic Function, cg package
Arguments: hbitmap &optional from-box texture texture-info
See get-pixmap, which provides a better interface to achieving what get-texture does.
This function was called get-pixels in earlier releases. The get-pixels symbol still exists and it names a function identical to get-texture.
This function copies all or part of the image displayed by a window or a bitmap handle into texture and texture-info objects. Two values are returned:
(1) texture containing the pixels copied from the window or bitmap handle, and
(2) texture-info structure that can be used during further processing of the pixel-map.
This function can be used to store pixels from a screen into a file by first calling get-pixels and then calling either save-pixmap (to save as a .bmp file) or save-lisp-pixmap (to save as a Lisp form).
stream-or-texture-handle identifies the object from which to copy the pixel-map. It can be a window, (screen *system*) (see screen and *system*), or a bitmap handle (as created by open-texture). If the window is a bitmap-window or bitmap-pane, then the pixels are copied from the memory bitmap associated with the window, and so the window does not need to be visible on the screen while copying from it. For other types of windows, pixels are copied from the window's interior as that region currently appears on the screen, so you may need to expose and redisplay the window before using get-texture on it.
from-box should be a box structure indicating the area of the window or bitmap handle to copy from. If this argument is not supplied, the page size of the window is used. The default page size for windows is the size of the screen, which causes this function to create very large pixmaps that often result in running out of memory. If this is a problem, you can either pass this from-box argument to specify a smaller area, or use a smaller page-width and -height for the window.
texture can be a scratch pixel-map array that you can pass to avoid creating a new object each time you call get-texture. If this argument is supplied and the texture is at least as wide and as tall as the area being copied, then it will be filled with the copied pixels and returned; otherwise a new pixel-map array is created, filled, and returned. The width of the texture should be a multiple of 32 (though the returned texture-info will contain the actual width of the copied area).
texture-info can be a scratch texture-info that you can pass to avoid consing a new one with each call. If this argument is supplied, it will be modified and returned as the second value; otherwise a new texture-info structure is created and returned.
Generic Function, cg package
Arguments: bitmap-pane-or-bitmap-stream &optional texture-info
This function returns a texture-info with information about bitmap-window-or-pane's width, height, and bits-per-pixel.
Note that the argument list has changed in release 7.0. Previously, the first argument was a stream, and the second specified the bitmap-pane or bitmap-stream of interest. The now-removed stream argument was in fact unused. All calls to the function written for earlier releases must be changed. The arguments now are:
bitmap-pane-or-bitmap-stream a bitmap-pane or a bitmap-stream about whose memory bitmap you would like to know the width, height, or bits-per-pixel.
texture-info a texture-info that you can pass to avoid consing a new one each time; if you pass a texture-info, get-texture-info fills in its fields; if you pass nil or do not specify this argument, a new texture-info is created.
Note that the texture-info as returned by this function does not include the colormap used by bitmap-pane-or-bitmap-stream. If you need the colormap included (as you do, for example, when you pass a texture-info to save-pixmap), use the texture-info returned as the second value by the slower function get-texture.
Generic Function, cg package
Arguments: drag-widget drop-widget position
Called when a drop is done over a control where droppable-p indicates that the drop is allowed.
The default method calls drop-get to retrieve some "dragged value" from the dragged control and then calls drop-put to tell the control over which the value was dropped to accept the new value in some way.
Generic Function, cg package
Arguments: window
This generic function has an effect only in web browser mode. It returns a boolean value that indicates whether mouse wheel events for the specified window are passed to mouse-wheel methods in CG, rather than letting the web browser do its default scrolling action.
The setf of this function can be called to set the current mode of a window, or it can be specified by when creating the window by passing a :grab-mouse-wheel argument to make-window. Typically the mode would not change during the life of a window, so the :grab-mouse-wheel argument is probably more convenient.
An application could alternately define a grab-mouse-wheel method that specifies which mode every instance of a window class should always have. That method would override the ability to call (setf grab-mouse-wheel) to switch the mode of a window.
function, cg package
Arguments: nodes center-x-reader center-y-reader width-reader height-reader
This utility function might be useful when using the function graph-layout to draw graphs and handle mouse events on them. The arguments should be the same as the same-named arguments to graph-layout. See that function for more information.
This function returns values that indicate the extent of all of the nodes in a graph. Four values are returned, which are real numbers. They indicate the left, top, right, and bottom sides of a rectangular region that encompasses all of the nodes in the graph. The units are whatever arbitrary units are returned by the reader functions that are passed as arguments to this function.
function, cg package
Arguments: &key *nodes links selected-node (selected-node-steps 8) fixed-nodes links-reader node1-reader node2-reader center-x-reader center-y-reader width-reader height-reader center-writer linear-links-reader redisplay-function cancel-function animate redisplay-at-end pause canvas (canvas-left 0)(canvas-top 0) (canvas-right 1000)(canvas-bottom 1000) extended-canvas-left extended-canvas-top extended-canvas-right extended-canvas-bottom (canvas-center-x (floor (+ canvas-left canvas-right) 2)) (canvas-center-y (floor (+ canvas-top canvas-bottom) 2)) (min-node-to-node-spacing 12) (min-link-to-node-spacing 12) (max-iterations 200) (work-from-current-layout t) (spacing-increment-for-many-links 15) (long-path-spacing-increment 15) (long-path-max-spacing 60) (num-links-before-extra-spacing 2) (iterations-for-extra-spacing 12) (limit-outward-stretching t) (protect-tail-node-positions t) (consider-alternate-spots-by-linked-nodes :after-crossed-links) (number-of-alternate-positions 3) consider-additional-leaf-positions ignore-crossed-tails exclude-tail-nodes-from-home-positions compress-layout-at-end center-the-graph
This function performs a graph layout by determining the positions to which a set of arbitrary user nodes (or vertices) should be moved to make the graph relatively readable when drawn in some way. It does not draw anything, but simply specifies where to move nodes. The drawing (rendering) aspect could be done with the Common Graphics nodes-and-links facility (see node-pane-mixin) or with some other rendering tool, either in Common Graphics or not.
The layout algorithm specializes in cyclic graphs, where it is non-trivial to arrange the nodes. It attempts to arrange the nodes so that nodes are near their neighbor nodes, but without any link lines (edges) passing through nodes to which they aren't connected. (Straight link lines between the centers of nodes are assumed.) It arrives at a solution incrementally by repeatedly moving individual nodes to better niches.
The algorithm will also lay out simple trees, though for trees it would usually be better to use a different layout algorithm that arranges things in a more regular directional pattern. This function would likely fit more of a tree into a given area, though in a less regular arrangement than a dedicated tree grapher.
This function can work with any sort of user data, as long as there is an object for each node (or vertex) and each link (or edge). This works by passing in accessor functions that return the current position and size of an arbitrary node object, or the list of links for a node or the two nodes for a link. One other access function that you pass in will be called repeatedly by this function to store a new position for a node. When this function returns, the calling application can then read the node positions that this access function stored somewhere, and then draw the graph in some way.
Three values are returned: (1) t or nil indicating whether the layout succeeded (see just below), (2) the number of iterations that were done, and (3) t or nil indicating whether the user canceled.
The term succeeded means reached a state where no further improvement could be made by moving a single node.
There is an example in the Navigator dialog that illustrates using this function along with the nodes-and-links facility for rendering. The example is called Custom Graphical Objects: A Nodes and Links Editor.
See also the utility functions graph-boundaries (which calculates a rectangle holding all nodes), center-all-nodes (which repositions nodes), and other-node which returns the node connected to a specified node by a link.
The many arguments to this function are grouped into four categories: Main, Accessor Function, Miscellaneous, and Option.
nodes is a list of some sort of node objects. It can be nil if a list of links is provided, in which case the accessor functions that you provide will find the list of all nodes from the links. Otherwise it should be a list to which the accessor functions can be applied to return information about the nodes, and to which the center-writer function can be applied to update a node's current position.
links is a list of some sort of link objects. It can be nil if a list of nodes is provided, in which case the accessor functions that you provide will find the list of all links from the nodes. Otherwise it should be a list to which the accessor functions can be applied to return information about the links.
selected-node may be nil if no node is to be treated as the special selected node. Otherwise it should be one of the nodes in the graph. This node will have a fixed position during the layout if selected-node-steps is nil, or else will be moved gradually during the layout to the center of the primary canvas.
selected-node-steps is the number of iterations that will be used to move the selected-node (if any) to the center of the canvas; if nil, then the selected-node (if any) will stay fixed at its current position.
fixed-nodes is a list of some subset of the nodes list. These nodes will not be moved at all during the layout. The other nodes will arrange themselves around the fixed nodes. This can be useful when changing the set of nodes that are displayed, to keep some or all of the existing nodes in the same place and arranging newer nodes around them, to retain context.
links-reader should be a function that accepts a node as a single argument and returns a list of that node's links.
node1-reader should be a function that accepts a link as a single argument and returns the first of the link's two nodes. This is generally the "subject" of a relation or the "from" node of some sort.
node2-reader should be a function that accepts a link as a single argument and returns the second of the link's two nodes.
center-x-reader should be a function that accepts a node as a single argument and returns an integer that indicates the current horizontal position of the center of the node.
center-y-reader should be a function that accepts a node as a single argument and returns an integer that indicates the current vertical position of the center of the node.
width-reader should be a function that accepts a node as a single argument and returns an integer that indicates the current width of the node.
height-reader should be a function that accepts a node as a single argument and returns an integer that indicates the current height of the node.
center-writer should be a function that accepts three arguments, namely a node, a center-x integer, and a center-y integer. It should update the current position of the node so that the center-x-reader and center-y-reader functions will return the x and y values when they are subsequently called on the node.
linear-links-reader should be nil if all link lines are allowed to point in any direction. Otherwise it should be a function that accepts a single argument, which will be one of the link objects that are passed in the list for the links argument. The function should return nil for a particular link if that link is allowed to point in any direction. Otherwise it should return one of the keyword symbols :upward, :downward, :leftward, or :rightward to indicate the direction that the link should point. The value :upward, for example, will force the node2 of the link to be at least somewhat higher than the node1 of the link in the layout. So :upward really means "more upward than downward" and the link line could, for example, point East by Northeast.
redisplay-function should be a function that accepts a single argument for some sort of canvas on which the layout will be drawn. Typically the argument is a window, and the function will simply invalidate the window so that it will redraw itself. It is then up to the window's usual redisplay function to examine the set of nodes and links and to redraw everything according to the node positions that have been established through calls to the center-writer function.
animate indicates whether the redisplay-function function is called multiple times to draw the layout as it is incrementally updated. If nil, the redisplay-function function is called only once at the end of the layout. If :node, then the redisplay-function function is called each time a node has moved. If any other true value, then the redisplay-function function is called once each time the entire set of nodes have had their positions updated. This last option is generally the better style of animation.
redisplay-at-end indicates whether the redisplay-function is called after the layout has finished. This is probably useful only when animate is nil, in which case it could be used when another call to graph-layout is about to be made (typically with different options), to suppress all redisplay until the final call to graph-layout.
pause indicates whether to pause each time the redisplay-function function is called. It may be nil for no pause, or a positive number indicating the number of seconds to pause. This simply calls sleep.
canvas should be some sort of object on which the layout will be drawn, such as a window. This object will simply be passed to the redisplay-function function and cancel-function whenever they are called.
canvas-left, canvas-top, canvas-right, and canvas-bottom should be integers that indicate the extent of the primary canvas into which graph-layout will attempt to fit everything. The units should be the same as those used by the accessor functions such as the center-x-reader and the center-writer. These are typically the extents of the currently visible part of a window, measured in pixels.
extended-canvas-left, extended-canvas-top, extended-canvas-right, and extended-canvas-bottom may either be nil to force everthing to fit onto the primary canvas, or else integers to indicate the extent of a larger canvas into which nodes will be moved when they cannot be fit acceptably on the primary canvas. The values should encompass the primary canvas extents. These are typically the extents of the entire canvas that can be scrolled into a window, measured in pixels. This appears to be useful when the extended canvas is somewhat larger than the primary canvas, but not when it is a lot larger. Therefore, if the needed canvas size is a lot larger than the available visible area of a window, it's probably best to pass ONLY a primary canvas range and make it be the size that's needed for the entire graph that can scrolled into a window.
canvas-center-x and canvas-center-y are integers that indicate the position that will be regarded as the logical center of the primary canvas, for such operations as moving the selected node to the center. When unspecified, they default to the actual center of the primary canvas.
min-node-to-node-spacing is an integer indicating the minimum distance that will be maintained (when feasible) between nodes. When upspecified, it defaults to 12.
min-link-to-node-spacing is an integer indicating the minimum distance that will be maintained between any link and any node to which it is not connected. When unspecified, it defaults to 12.
max-iterations is the maximum number of times that all nodes will be potentially moved to better locations. Typically graph-layout will reach a stable state and return within a couple of dozen iterations. If max-iterations is reached before a stable state is reached, then graph-layout will stop iterating prematurely, though the current state that it leaves might still be usable. If explicitly passed as nil, it will default to 50.
work-from-current-layout indicates whether to begin moving nodes incrementally from their current positions, rather than beginning with all nodes in the center of the canvas. True is useful for moving from one state to another interactively in such a way that user may be able to follow nodes of interest to their new locations. nil typically creates a cleaner layout, though, by removing any bias in the nodes' current positions before beginning.
spacing-increment-for-many-links is an integer indicating how much space to reserve from the center of a node for each link that it has beyond four links. Other nodes and links will avoid overlapping this extra space. This prevents another node from sitting close to a highly-linked node and blocking a large arc of angles from which other link lines could emanate.
long-path-spacing-increment indicates how much additional space should be required between nodes when the shortest path between the two nodes is relatively long. This helps to keep separate branches farther apart so that it's easier to tell that they are distinct groups of nodes. It may also decrease the amount of tangling of unrelated branches of nodes. This feature may slow down the layout a little and makes it use up somewhat more space, but usually results in a cleaner layout. If long-path-spacing-increment is nil or zero, then nothing is done. Otherwise the specified value will be added to the required distance between a node and another node or link for each link in the shortest path between the two objects beyond the first num-links-before-extra-spacing links. For example, if num-links-before-extra-spacing is 4, long-path-spacing-increment is 15, and the shortest path between two nodes is 7 links long, then graph-layout will add (* 15 (- 7 4)) = 45 pixels to the usual min-node-to-node-spacing value to determine how far apart it will try to keep those two nodes.
num-links-before-extra-spacing is the number of links in the shortest path between two nodes (or a node and a link) before the long-path-spacing-increment will be added for each additionl link, when long-path-spacing-increment is a positive number.
long-path-max-spacing is the maximum additional pixel distance that will be required between two nodes whose connecting path is long. This is used only when long-path-spacing-increment is a positive integer. If long-path-max-spacing is nil, then no maximum is used.
iterations-for-extra-spacing is the number of iterations at the beginning of a full layout (when work-from-current-layout is nil) during which long-path-max-spacing will be set to a higher number than the argument that was passed. The first iteration will set that parameter to a much larger value, and the increase will be reduced on successive iterations until it is the argument value after iterations-for-extra-spacing iterations. If this argument is nil or zero then long-path-max-spacing is not increased. A positive value here may get the layout off to a better start by initially keeping distantly-linked nodes farther from each other than they would otherwise be. This can result in fewer crossed branches of nodes.
limit-outward-stretching, when true, will avoid moving nodes toward the edges of the canvas as much, to prevent stretching out the graph a lot more than necessary.
consider-alternate-spots-by-linked-nodes indicates whether to consider alternate positions than the usual ones that extend from the linked nodes of a node that is being moved, on some iterations. When true, this may result in a better final layout, but may take longer or be less smooth for an interactive update. The special value :after-crossed-links, which considers alternate positions for a node only after an iteration where no spot was found for the node without crossed links, might be a good general compromise. It is the default.
number-of-alternate-positions is the number of extra positions to each side of a linked node to consider, when consider-alternate-spots-by-linked-nodes is true.
consider-additional-leaf-positions will look for places to move leaf nodes that extend orthoganally from each of the nodes that are linked with the single node to which the leaf node is linked; this takes longer but may result in a better graph.
protect-tail-node-positions indicates whether nodes in a tail are allowed to maintain their current positions like any other node, rather than being moved to make room for more highly-connected nodes. True is better for interactive layouts, to reach a final state sooner, though nil may result in a better final graph.
ignore-crossed-tails indicates whether to do nothing special about tail nodes whose links cross other links, perhaps needlessly, rather than making a special effort to uncross them. True is faster for interactive graphs, but it does not appear to take much time, so perhaps nil is always best for this argument.
exclude-tail-nodes-from-home-positions might make a difference in the layout by not considering linked nodes that are in tails when calculating the ideal position to which to move a node.
compress-layout-at-end indicates whether to pull some nodes in closer to the center of the graph after the layout has reached its otherwise final state. The layout tends to spread nodes throughout the available space on the primary canvas, as part of the algorithm for a good layout, and doesn't know when it is about to reach a stable state. Passing this argument as true executes an unrelated algorithm at the end to compress the nodes somewhat, though some arrangements of nodes toward the outside will not be pulled in at all. This option is purely a matter of preference.
center-the-graph, if true, causes the entire graph (the block that encompasses all nodes) to be moved to the center of the canvas at the end of the layout. If the value is :after-each-iteration, then it is also centered after each iteration; this may improve the layout by maximizing the minimum amount of margin that's available on any side of the graph during the layout, but may make an animated layout jerk back and forth.
Generic Function, cg package
Arguments: stream object
Returns t if object is a valid graphics-context for stream, and returns nil otherwise. Currently returns t for any windows-graphics stream with any graphics-context object, but in the future different kinds of stream may require different graphics-contexts. stream should be a cg-stream.
See copy-graphics-context (where all the information in a graphics-context object is described), make-graphics-context, set-graphics-context, and restoring-graphics-context.
Generic Function, cg package
Arguments: widget
Returns the grid-widget containing the argument, which should be usually a grid column, row, or section.
Generic Function, cg package
Arguments: grid-widget buttons
Called when the small square at the lower right corner of the grid is clicked.
Generic Function, cg package
Arguments: grid-widget buttons column-section column-section-border-p column column-num column-border-p x row-section row-section-border-p row row-num row-border-p y &optional trigger-key
This method is called whenever the user clicks on the grid. Normally calls the cell-click method, except for when the user has clicked a special non-cell area around the edge of the grid.
Function, cg package
Arguments: stream string box &optional wrap-p horizontal-justification vertical-justification calculate-height
Intended as a variant of draw-string-in-box suitable for using in grids, in fact this function provides nothing additional and draw-string-in-box should be used in its place (draw-string-in-box has more arguments but the common arguments are the same and the extra draw-string-in-box arguments should be specified nil when converting a call from this function).
As with draw-string-in-box, text is drawn if the value of the calculate-height argument is nil (the default) and not if the value of that argument is true. In either case, the height of the wrapped text, if it were drawn, is returned. See draw-string-in-box for more details.
Generic Function, cg package
Arguments: grid-top-pane
This method returns the grid-drawing-pane instance associated with the argument. This is the widget-window on which a grid-widget is drawn except for its outermost border.
The grid-top-pane argument is the main widget-window (returned by the function window) of a grid-widget. It is an instance of the grid-top-pane class, and is the parent of the grid-drawing-pane.
See grid-drawing-pane-class-for-grid for information on subclassing the grid-drawing-pane of a grid-widget.
Generic Function, cg package
Arguments: grid-widget
This method returns the name of the grid-drawing-pane class that a grid-widget should instantiate for the drawing area of the grid. This method may be useful in unusual cases where the widget-windows of a grid-widget need to be subclassed.
Every dialog-item instance that is placed onto a parent window has an associated widget-window or lisp-widget-window instance for the actual window that appears on the screen for the dialog-item. In atypical cases where it is necessary to subclass a widget-window class along with a dialog-item class, a widget-device method is written to tell the dialog-item subclass which widget-window or lisp-widget-window subclass to instantiate automatically.
A grid-widget is a special case in that it has an additional associated widget-window. This window is a child of the main widget-window and contains the entire grid body except for the border at the outside edge of the grid. If this window needs to be subclassed as well, then a grid-drawing-pane-class-for-grid method should be written to tell the grid-widget subclass which grid-drawing-pane subclass to use, just as the widget-device method tells it which grid-top-pane subclass to use. The method should take a grid-widget instance as its only argument and return the name of a subclass of grid-drawing-pane.
There should be no need to subclass a grid-widget's widget-window classes in typical applications that add cell-click, cell-key-down, and draw-cell methods to handle events and drawing on a grid. But if that API is not sufficient and it is necessary to write methods for a grid on lower-level generic functions such as mouse-left-down or virtual-key-down, then the grid-drawing-pane class may be subclassed to provide a class on which to specialize these methods.
The function grid-drawing-pane (called on the main widget-window of a grid-widget) returns the grid-drawing-pane just as the function window (called on a dialog-item) returns the main widget-window.
Here is the default method:
(defmethod grid-drawing-pane-class-for-grid (grid-widget)
(declare (ignore grid-widget))
'grid-drawing-pane)Generic Function, cg package
Arguments: grid-widget column-section column-section-border-p column column-num column-border-p x row-section row-section-border-p row row-num row-border-p y
Returns the mouse cursor to use when the mouse is over some part of a grid.
Generic Function, cg package
Arguments: grid-widget x y
Returns multiple values indicating the component of a grid that lies at a certain spot in the grid-widget window. The values are as if from the form:
(values column-section column-section-border-p
column column-num column-border-p
x
row-section row-section-border-p
row row-num row-border-p y)Function, cg package
Arguments: grid-widget across-p forward-p section-p
Move the keyboard focus within grid-widget by one cell or one section.
The remaining arguments are booleans.
If across-p is true, then the focus is moved horizontally from one grid-column or column-section to another. If it is nil, the focus is moved vertically from one grid-row or row-section to another.
If forward-p is true, then the focus is moved either rightward (when across-p is true) or downward. When it is nil, the focus is moved either leftward or upward.
If section-p is true, then the focus is moved to the next grid-section. When it is nil, the focus is moved to the next cell within the current section. When moving into another grid-section, the focus is placed wherever it was most recently in that section, or else in the upper left cell if that section has not yet had the focus.
If there is no next cell or section in the requested direction, then the focus is not moved at all.
The arrow keys perform this functionality when a grid-widget has the keyboard focus, moving by sections rather than cells if the Control key is being held down.
Function, cg package
This function is named by an exported symbol because that symbol also names the group-box class. The function is internal and not for user code.
Generic Function, cg package
Arguments: dialog-item
This function is likely no longer needed for any purpose. It can only be specified with an initarg since it is not a property.
A widget with the groupstart attribute allows you to use the arrow keys to move the keyboard focus among the widgets between the groupstart=t widget and the widget just before the next groupstart=t widget in the tab order. The idea was that you would normally tab to the first button in a group (which would have both tabstop and groupstart on), and then use the arrow keys to move to the other buttons in the group. Pressing TAB would jump all the way to the next widget after the button group, because typically only the first of those buttons would have a tabstop.
Modern interfaces seem to put a tabstop on each button, though, instead of just the first one in the group, except for radio-buttons, where the OS seems to force the tab to go to the selected radio-button, from where you can use the arrow keys to change the selected button to be one of the other radio-buttons in the group (where the group is just the set of radio-buttons that are contiguous in the tab order, which is not necessarily the same as the common graphics cluster, though it probably should be set up as the same group for a good design).
Function, cg package
Arguments: window
Returns the integer that the operating system uses to identify a window. An application should need this function only if it is programming partly in Common Graphics and partly at the Windows API level, in which case this function returns the handle of a Common Graphics window to pass directly to Windows API functions that require the window handle. The related function device-context returns the device-context integer.
The home package of the symbol naming this function is windows but it is also exported from the common-graphics package. (This is necessary because handle is exported from another package used by the common-graphics package.) Note that this function is not available in images into which the Common Graphics module has not been loaded.
Generic Function, cg package
Arguments: outline
Returns whether an outline widget will draw its outline-items above their parent items whenever their above-parent properties are true. The value may be set at any time with (setf handle-above-parent). The default value is nil.
If some outline-items are given a true above-parent value, then the outline could be switched back and forth between two different views of the data by toggling the value of this handle-above-parent property.
Generic Function, cg package
Arguments: window
A generic function that is called whenever the built-in timer returned by (cg-timer) fires. Normally, this timer is always active (but see use-cg-timer), and it calls this generic function to direct its timer messages to the currently selected window. Specifically, handle-cg-timer is first called on the selected-window of the screen. The default handle-cg-timer method then calls handle-cg-timer on that window's selected window, and this is done recursively over successive child windows until either a more specific handle-cg-timer method is called, or there is no further selected-window.
Common Graphics internally uses various handle-cg-timer methods on particular types of windows. Applications may also add handle-cg-timer methods for any of its window classes if it is useful for such a window to receive timer messages only when it is the selected window (which is normally the window that has the keyboard focus). A set-focus method for the window class could set the interval of the (cg-timer) as appropriate for that window, since Common Graphics always sets the interval back as needed when using it internally.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: window
This function is no longer used. It was related to the GTK version of CG, which is no longer supported.
Generic Function, cg package
Arguments: outline
Returns whether an outline widget will handle certain keystrokes near the middle of the main part of the keyboard as easy-to-reach alternatives to the arrow keys and Home and End keys. The value may be set at creation time by passing the handle-home-key-shortcuts initarg to make-instance when creating the widget, or any time later by calling (setf handle-home-key-shortcuts).
This option is disabled by default, though in the IDE it is enabled in the outline widgets of the standard IDE tool dialogs.
When this option is enabled, the letter keys at the left in the following table are interpreted just like the standard keys to their right that are always handled. Though the letters are shown in uppercase here (as on keyboards), you just need to press the keys by themselves (unshifted).
J DownArrow selects the next outline item
K UpArrow selects the previous outline item
F RightArrow opens the selected outline item
D LeftArrow closes the selected outline item if it is open,
or else selects the parent item
T Home scrolls to the top and selects the first item
B End scrolls to the bottom and selects the last itemGeneric Function, cg package
Arguments: menu menu-item-or-item-number window-or-screen
Called to process a menu-item that was chosen by the end user (either by clicking on it or first selecting it and then pressing the main Enter key).
The default method first checks to see if the value of the chosen menu-item is another menu. If so, it calls pop-up-menu on that menu. Otherwise it funcall's the value of the on-click property of the menu, passing three arguments:
the menu that was passed to this function
the chosen menu-item
the stream that was passed to this function, which is either a window or the screen
menu is the menu that contains the chosen menu-item.
menu-item-or-item-number is either the menu-item that was chosen, or the index of the item within the menu-items of the menu, where zero indicates the topmost menu-item.
window-or-screen is either the window on which the menu was invoked with pop-up-menu, or else the window on which the menu was defined or the screen.
The default handle-menu-selection method should suffice for most applications, since menus are typically customized by a combination of menu-item values and (when needed) custom on-click event handlers.
But an application could replace the default handle-menu-selection method with one that bypasses the on-click functionality entirely. Or an application could add handle-menu-selection wrapper methods that catch every menu choice for some class of menu.
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: ocx-widget-window buttons key-code
Applies to the Windows platform only.
This is a tentative function because we are not sure how keypress events should properly be intercepted from OCX controls, which normally define their own complete keyboard event handling. This functionality may change in the future.
This generic function will be called when a keypress event occurs while an ocx-widget-window has the keyboard focus. An application could add methods to intercept the keypress from the control's usual handler. True should be returned to suppress the control's own built-in handling of the keypress (if any), or nil to allow it.
The default method does nothing and returns nil. A method for html-widget-pane calls virtual-key-down with the same arguments that were passed to handle-ocx-shortcut; this allows keystrokes in the html-widget-for-browser pane of an html-browser dialog (for example) to invoke the dialog's toolbar buttons. You may find it useful to define a similar handle-ocx-shortcut method for ocx-widget classes that you define. See def-cg-ocx-control.
Generic Function, cg package
Arguments: window
Returns whether a window or widget will automatically interpret certain keystrokes for scrolling. The value may be set by passing the :handle-scrolling-keys initarg when creating the window or widget, or any time later by calling (setf handle-scrolling-keys).
window-or-widget should be either a regular window (an instance of basic-pane or any of its subclasses other than widget-window) or a lisp-widget. This facility does not apply to os-widgets because they always handle their own scrolling internally.
If the value is nil, then the window or widget will not scroll when the usual scrolling keys are pressed; an application would need to handle this itself in a virtual-key-down method. If the value is :page, then the PageUp and PageDown keys will scroll the window vertically by a page, or horizontally by a page if the control-key is held down. Except in CG/JS mode the alt-key is used instead of the Control key, because most web browsers intercept Control+PageDown and Control+PageUp to switch to an adjacent browser tab. If the value is :vertical, then the up and down arrow keys will scroll by a line vertically, in addition to PageUp and PageDown being handled vertically as with :page. For any other true value, the left and right arrow keys will scroll horizontally by a line, in addition to all of the :vertical keys being handled. For any true value, the Home and End keys will scroll to the top and bottom of the scrollable canvas respectively, and for any true value other than :vertical the Home and End keys will scroll to the left and right of the scrollable canvas respectively if the Control key is held down. The default value is nil.
The scrolling is done by calling scroll. The scrolling distance that is passed to scroll is found by calling scroll-increment.
This facility is implemented in the default virtual-key-down method for basic-pane. If a more specific virtual-key-down method overrides the default for these keystrokes, then the automatic scrolling will not be done.
Generic Function, cg package
Arguments: outline-item
This outline-item property allows an outline-item to avoid displaying a leaf pixmap when a custom range-on-open method is expected to supply child items for it later when it is opened.
has-range-on-open returns nil by default, but may be set to true if needed by calling (setf has-range-on-open) or, more typically, by passing the :has-range-on-open in make-instance when creating an outline-item.
An application should set this property to true if the item has no child items initially but a range-on-open method that the application has supplied for this outline is expected to return one or more child items for this item. If no custom range-on-open method is supplied for this outline, then there is no need to set the value of the has-range-on-open property.
An outline-item will display its outline-item-leaf-pixmap (rather than its outline-item-opened-pixmap or its outline-item-closed-pixmap) when it currently has no child items (that is, its range is nil) and when its has-range-on-open property is nil. Otherwise it will display its opened or closed pixmap, depending on its current state (assuming that draw-icons is enabled for the outline). The plus or minus pixmap is also displayed whenever the leaf pixmap is not displayed (assuming that draw-plus-minus is enabled for the outline).
Generic Function, cg package
Arguments: basic-pane
Returns true if the argument (a pane) has a toolbar. Returns nil otherwise. See the display-toolbars property and the toolbar class.
Generic Function, cg package
Arguments: header-control &optional (header-id (value header-control))
Returns the header-info for the header with an id of header-id on header-control, or nil if header-control has no header with that id.
See the description of the header-control class/control.
Generic Function, cg package
Arguments: header-control position-in-header-control
Returns the header-id of the header at position-in-header-control relative to the upper left corner of header-control, or nil if that position is not over a header.
See the description of the header-control class/control.
Generic Function, cg package
Arguments: header-defaults-or-header-cell
Returns the background-color of a header-cell, column-header-defaults, or row-header-defaults object (passed as the header-defaults-or-header-cell argument), or sets the value with the setf of this function. This value is used when cell-background-color is called while drawing the header-cell of a grid-row or grid-column.
Generic Function, cg package
Arguments: header-control header-id
Returns a box indicating the region occupied by the header whose id is header-id on header-control, relative to the upper left corner of header-control. Either this or default-header-width could be used to determine how to align columns of information below the header-control's headers.
See the description of the header-control class/control.
Generic Function, cg package
Arguments: grid-subsection
Returns the header-cell of grid-subsection, which is a grid-row or a grid-column. A header-cell specifies style properties that will be used when drawing a grid cell that is in the row or column and which is also in an intersecting column or row whose name is :header. If there is no intersecting subsection named :header, then these property values will not be used.
Typically a grid-widget will have a first row section whose name is :header, which has a single row whose name is also :header. When the top cell of any grid-column is drawn in that case, it will look in this header-cell child of the grid-column for any drawing style properties that should override the usual properties of the grid-column.
The values of this object's properties can be the same as the values of the same properties of grid rows and columns. They can also be the special keyword symbol :defer, which means that the header cell should use the same value for that property as the other cells in that row or column. The values are initially :defer for each property, allowing you to override only the particular properties that should differ for the header cell only.
In general, specifying properties for individual cells is problematic due to the large number of cells in a typical grid. But a typical grid has only a single header row and/or a single header column, and often it's desirable to make header cells differ somewhat stylistically, so this header-cell object is provided for this typical case.
Generic Function, cg package
Arguments: grid-widget
Like body-column-count, except for a column-section named :header. Typically the value would always be either 1 (for a single header column) or 0 (for no header column-section at all).
If (setf header-column-count) creates the section, it will always be added as the first section. And (unlike body-column-count) if the new number is zero, then the section will be removed entirely.
See body-column-count for more information as the operators are similar except as noted.
Generic Function, cg package
Arguments: grid-widget
This is like body-columns, except for a column-section named :header rather than :body. See that page and make the appropriate substitutions, as that makes clear the functionality is essentially the same.
Generic Function, cg package
Arguments: header-info
Returns the header control that contains the argument header-info object. See the description of the header-control class/control.
Generic Function, cg package
Arguments: header-control header-id
Returns the value of the fill-space property of the header-id on header-control. If true, the header-id will expand to fill available space when the header is made bigger. Initially, only the rightmost header has a true fill-space property.
See the description of the header-control class/control.
Generic Function, cg package
Arguments: object
Returns true if object is an instance of the class header-info; returns nil otherwise.
See the description of the header-control class/control and the header-info class.
Generic Function, cg package
Arguments: header-control header-id
Returns the justification of header-id in header-control. See the description of the header-control class/control.
Generic Function, cg package
Arguments: header-control header-id
Returns the label of header-id in header-control.
See the description of the header-control class/control.
Generic Function, cg package
Arguments: grid-widget
Like body-row-count, except for a row-section named :header. Typically the value would always be either 1 (for a single header row) or 0 (for no header row-section at all).
If (setf header-row-count) creates the section, it will always be added as the first section. And (unlike body-row-count) if the new number is zero, then the section will be removed entirely.
See body-row-count for more information as the operators are similar except as noted.
Generic Function, cg package
Arguments: grid-widget
This is like body-rows, except for a row-section named :header rather than :body. See that page and make the appropriate substitutions, as that makes clear the functionality is essentially the same.
Generic Function, cg package
Arguments: header-control header-id
Returns the width of header-id in header-control. See the description of the header-control class/control.
Generic Function, cg package
Arguments: list-view
Returns the value of the headers property of the argument. The value can be t (have headers) or nil ( do not have headers). A header is a row of column headers, each using the column title as its title. Headers are typically mouse-sensitive. Clicking on a header sorts the contents of the control alphabetically according to the entries in the clicked column.
The headers property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :headers initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
See the list-view class/control.
Generic Function, cg package
Arguments: standard-object
Returns the height of the argument.
Generic Function, cg package
Arguments: basic-pane
This window property has an effect only when running in Windows desktop mode.
Returns whether basic-pane has a "question mark" button in its title-bar for invoking context-sensitive help. If the user clicks this button and then clicks a dialog-item or child window of basic-pane, then the generic function context-sensitive-help is called. An application can add methods to context-sensitive-help to display help on the clicked dialog-item or child window.
Microsoft Windows Note: due to operating system design, this button may not be used along with the minimize or maximize buttons (see minimize-button and maximize-button). Those buttons will not appear if specified along with the help-button option.
This property should be specified by passing a help-button initarg to make-window, since this property cannot be changed on an existing window by calling setf and this generic function. (You may also specify it interactively in the inspector for a form window; the button will not appear on the form itself but will appear on the running window of the form.)
Generic Function, cg package
Arguments: window
This generic function is called whenever the user left-clicks the "question-mark button" on the frame of a frame-window that has the help-button property. window is the frame-window that has the help-button that was clicked. Applications may override the default method in order to tell the user what to do next in some custom way.
The behavior of the help-button is hard-wired to wait for the user to left-click a control or child window in that window, and to then call context-sensitive-help with that control or child window (unless the user cancels by pressing the ESCAPE key or clicking elsewhere). help-button-pressed is therefore useful only for telling the user to click on a control or child window in that window for some reason.
The default method calls window-message on window with the string "Left-click a control in the same window for help on that control." Due to the general functionality of window-message, this string will appear in the window's status-bar or common-status-bar if the window has one, or else will appear in an ancestor window's status-bar or common-status-bar, if any.
Generic Function, cg package
Arguments: standard-object
Returns the help string of the specified object, or nil if it does not have a help string. (setf help-string) may be called to set the help string of an object; the value should be either a string or nil.
This value is not used internally except in the IDE where the help-string of any dialog-item will be displayed in the IDE's status-bar after the mouse cursor has paused over the widget. This property is provided simply to facilitate storing help strings for individual objects so that an application could retrieve and display them in some arbitrary way. A help-string will be displayed automatically when the mouse is over an object if the object's show-help-string-under-mouse property is true and a suitable status bar is found.
Methods of interest exist for the classes dialog-item, basic-pane, hotspot, menu-item, button-info, and property.
See show-tooltip for an example of displaying dialog-item help-strings whenever the mouse has paused over any widget.
Generic Function, cg package
Arguments: multi-picture-button
Returns a list of the names of multi-picture-button's buttons that currently do not appear on the widget at all. multi-picture-button must be a multi-picture-button. The value may be set at creation time by passing the hidden-buttons initarg, or any time later by calling (setf hidden-buttons).
The value should be a list of symbols, where each symbol is the name of one of the button-infos in the range of multi-picture-button. The default value is nil.
This property is useful for temporarily removing one or more buttons completely from view, in a way that makes it easy to restore them later to their usual positions within multi-picture-button.
An alternative is the unavailable-buttons property, which grays out buttons and makes them unusable while leaving them present in their usual positions. A more basic alternative is to modify the range property.
Function, cg package
Arguments: window
Disables the caret of window. The caret of window will be re-enabled either through a call to show-caret or when window receives the keyboard focus.
Function, cg package
Arguments:
This function exists only on the Windows platform. On Linux and the Mac, Allegro CL and the IDE are typically started from a shell window or an Emacs buffer and that window/buffer serves the function that the console does on Windows.
Hides the Allegro console window if it exists and is currently visible, and otherwise does nothing. See also show-console.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
Generic Function, cg package
Arguments: outline &key move-to-parent-only
Causes the child items of the currently selected outline-item to be hidden, unless move-to-parent-only is true or the selected item is already closed, in which case it will instead select the parent item of the selected item. This function is otherwise similar to close-outline-item-value except that it works on the currently selected item rather than on the item that has a specified value.
This function could be called directly for an interactive command to close the selected item, moving to the parent item if it already closed.
Generic Function, cg package
Arguments: widget
This is called internally to hide the tooltip of a widget when the mouse has moved off of it. It can also be called by an application, though that's probably useful only to hide a tooltip that was shown by calling show-tooltip-explicitly.
For either of those cases, wrapper methods could be added to this generic function to implement side effects when a tooltip is removed from a control. This may be useful, for example, to remove some other form of help that is displayed for a control.
Note that this generic function is called even if the show-tooltips configuration option has been turned off. This allows showing some custom form of help for a control without using tooltips, which may be handy if tooltips are considered more annoying than a status-bar message, for example.
See also show-tooltip.
Generic Function, cg package
Arguments: outline
When true, moving the mouse cursor over the an outline widget will highlight each outline-item when the mouse cursor is over it. This might help with reliably clicking the intended item. The default value is nil.
The highlighted outline-item under the mouse cursor will be drawn in the colors that are returned by outline-item-highlighted-foreground-color and outline-item-highlighted-background-color.
Generic Function, cg package
Arguments: chart-view
Returns the value of the high-low-fill-colors property of a chart-view. The value may be set at creation time by passing the high-low-fill-colors initarg, or any time later by calling (setf high-low-fill-colors).
The colors that are used to fill annotations that are drawn for :high-value and :low-value values in a chart-widget. The value should be a list of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list of the symbol yellow.
When the high-low-value-style property of the chart-view is either :bar or :diamond, these colors are used to fill the bar or diamond shapes. This property is not used when the high-low-value-style is :tee.
If the values is nil, then all bars and diamonds are filled with yellow. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.
See set-chart-value for an explanation of high and low values. See also high-low-value-style and high-low-tee-colors.
See chart-widget and also cg-chart-widget.
Generic Function, cg package
Arguments: chart-view
Returns the value of the high-low-tee-colors property of a chart-view. The value may be set at creation time by passing the high-low-tee-colors initarg, or any time later by calling (setf high-low-tee-colors).
The colors that are used to draw tee-style error bars for any :high-value and :low-value values in a chart-widget. The value should be a list of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list of the symbol red.
When the high-low-value-style property of the chart-view is :tee, these colors are used to draw the tee lines. This property is not used when the high-low-value-style is :bar or :diamond.
If the value is nil, then all tees are drawn in red. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.
See set-chart-value for an explanation of high and low values. See also high-low-value-style and high-low-fill-colors.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-view
Returns the value of the high-low-value-style property of a chart-view. The value may be set at creation time by passing the high-low-value-style initarg, or any time later by calling (setf high-low-value-style).
A value indicating the particular style in which any :high-value and :low-value values in a chart-widget are currently drawn. Here are the possible values:
:tee - Each value is drawn as a thin line from the main value to the high or low value, with a short perpendicular line drawn at the high or low value to form a tee. This style is commonly used to show an error range around a main value. This is the default value.
:bar - Each value is drawn as a filled rectangular bar from the main value to the high or low value. This may be useful when a more prominent annotation is desired than the more common :tee style.
:diamond - Each value is drawn as a triangle with a base at the main data value and proceeding to a single point at the high or low value. When there is both a high and a low value, the overall shape is that of a diamond. This style tends to look heavy-handed on a line graph, but may be more useful on a bar chart.
See also draw-high-low-values, high-low-fill-colors, and high-low-tee-colors.
See chart-widget and also .
Generic Function, cg package
Arguments: outline
Returns the value of the highlight-ancestors property of an outline control. The value may be specified at creation time by passing the highlight-ancestors initarg to make-instance, or any time later by calling (setf highlight-ancestors).
This is a boolean value indicating whether the outline widget will draw the background of each ancestor outline-item of the currently selected item in a different color. That can help the user to more easily see which items the selected item is indented beneath. When true, the background of each ancestor item will be drawn using the ancestor-background-color.
The default value is nil, for backward compatibility reasons, though it may generally be preferable to enable this behavior.
Generic Function, cg package
Arguments: calendar-widget
A boolean value indicating whether today's date should be drawn in a different style in a calendar widget to highlight it. By default it is drawn with red text, though the style can be controlled with the cell-style-current-date property.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: hotspot &key off
This generic function is called internally whenever a hotspot may need to be highlighted or unhighlighted. The default method will draw or erase highlighting if the hotspot's highlight-style is :invert or :outline (rather than nil).
hotspot is the hotspot that could be highlighted or unhighlighted. off will be nil when the hotspot should be highlighted, or true when it should be unhighlighted.
If the default highlighting styles are not adequate, an application could supply its own highlight-hotspot method to draw the highlighting in some arbitrary way. The default method sets the paint-operation to po-xor so that it can draw and erase the highlighting without any knowledge of what is drawn beneath the highlighting. A custom method could do likewise, or it could draw in the usual po-replace mode. In the latter case, erasing the highlight consists of drawing whatever is usually drawn in the window without redrawing the hotspot highlighting over it. So a custom method could simply call invalidate on the hotspot when the off argument is true (which will cause the window's redisplay-window method to redraw that area without the highlighting), and draw any sort of hotspot highlighting when the off argument is nil. The method can call hotspot-region on the hotspot to find the coordinates of the hotspot, and call region-box on that region to find the smallest box that contains the hotspot's coordinates.
Specifically, highlight-hotspot is called by the default mouse-in and mouse-out methods for hotspots. It is also called by a redisplay-window method for hotspot-mixin whenever there is a hotspot under the mouse while the window is being redisplayed for any reason. The off argument will be true if and only if the call is made by mouse-out.
Here is an example of a custom highlight-hotspot method. It is used by the Navigator's hotspots example when its Custom Opaque Highlighting check-box is checked. (See the Navigator dialog and the hotspot example titled Hotspots: mouse-active highlighting regions.)
(defmethod highlight-hotspot ((hotspot my-hotspot) &key off)
;; This is an example of a custom highlight-hotspot method
;; that an application might define instead of using one of
;; the two built-in highlighting styles.
;; This draws opaque highlighting rather than xoring
;; screen colors as the built-in styles do.
;; If we are turning the highlight off, then just invalidate
;; the hotspot so that the window's redisplay-window method
;; will be called to redraw the hotspot's region without the
;; hotspot highlighting.
(if* off
then (invalidate hotspot)
;; Otherwise draw highlighting over the top of whatever
;; is usually drawn in the window.
else (let* ((window (parent hotspot))
(region (hotspot-region hotspot)))
(with-background-color (window yellow)
(with-foreground-color (window black)
;; This interprets all four kinds of hotspot-region.
;; A simple orthogonal rectangle hotspot.
(cond ((boxp region)
;; Defer to the built-in highlighting for
;; box hotspots.
(call-next-method))
;; A polygon hotspot.
((or (vectorp region)
(cddr region))
;; These "erase" functions really draw,
;; but in the current background color.
;; So fill with the background color.
(erase-contents-polygon window region)
;; And outline in the foreground color.
(draw-polygon window region))
;; A circle hotspot.
((integerp (second region))
(erase-contents-circle window (first region)
(second region))
(draw-circle window (first region)
(second region)))
;; A line hotspot.
;; Use with-clipping-box here to prevent this
;; thick line from extending outside the
;; region-box that will be erased by a simple
;; call to invalidate on the hotspot.
(t (with-clipping-box (window (region-box region))
(with-line-width (window 10)
(with-foreground-color (window blue)
(draw-line window (first region)
(second region))))))))))))Generic Function, cg package
Arguments: hotspot
Returns the type of highlighting that the built-in highlight-hotspot method will use to highlight hotspot when the mouse cursor is over its hotspot-region. hotspot should be a hotspot instance, as created with make-instance. The highlight style may be specified by passing the :highlight-style in make-instance, or by calling (setf highlight-style) any time later.
The default value is :invert, which inverts the screen colors in the hotspot-region. An alternate style is :outline, which inverts only the edge of the region. By "inverts" we mean that the hotspot-region is filled or drawn while the paint-operation of the hotspot's parent window is set to po-xor. This allows the highlighting to be erased without knowledge of the "real" object that is drawn in the window where the hotspot lies. Though the highlighting is drawn with the foreground-color of the window set to the color of the hotspot, this will be the resulting color only where the window background is white, due to the way that po-xor works.
The other valid value is nil, in which case the default highlight-hotspot method does nothing at all. The hotspot is still sensitive to the mouse, but does not add any visual indication of this as the mouse moves over it.
If neither of the built-in highlighting styles is adequate, an application could instead supply its own highlight-hotspot method that ignores the hotspot's highlight-style property and draws some other sort of highlighting.
Generic Function, cg package
Arguments: tab-control tab-info-or-name &key off
Adds highlighting to a tab of a tab-control, so that it stands out among the other tabs, or removes highlighting that was added to a tab. Highlighting is effected by drawing the tab in the end user's colors for selected objects (such as highlighted menu-items or the title-bars of selected windows). Multiple tabs may be in the highlighted state simultaneously by calling this function multiple times, specifying different tabs.
tab-control should be a tab-control widget. tab-info-or-name should be either a tab-info object or its name, to specify which tab to highlight or unhighlight. If off is nil (the default), then the tab will be placed into the highlighted state, and otherwise it will be unhighlighted.
Generic Function, cg package
Arguments: app
Returns the handle of the running executable, as used in the Windows API. This handle value may be needed when programming directly in the Windows API rather than solely in Common Graphics.
app is an instance of the app class. Its current value is the value of
An application accesses the hinst value using the form
(hinst (app *system*))whether in the IDE or a standalone application.
hinst is a property of the app class.
Function, cg package
Arguments: struct
Returns the hue value of the argument, which must be an hls color object. See make-hls.
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
Function, cg package
Arguments: struct
Returns the lightness value of the argument, which must be an hls color object. See make-hls.
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
Function, cg package
Arguments: object
Returns true if object is an hls color object and returns nil otherwise. See make-hls.
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
Function, cg package
Arguments: struct
Returns the saturation value of the argument, which must be an hls color object. See make-hls.
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
Function, cg package
Arguments: hls-triple
Returns the rgb color object equivalent to the hls color object passed as the argument. See make-hls, make-rgb, and rgb-to-hls.
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
Function, cg package
Arguments:
Returns the user's home directory on Linux or their personal Documents directory on Windows, or nil if somehow there isn't one. This may be useful for finding a directory in which to save utility files for the current user. In case it is informative, here is the source code:
(defun home-directory ()
#-mswindows
(pathname-as-directory (or (system:getenv "HOME")
(translate-logical-pathname "sys:")))
#+mswindows
(or (win:special-windows-directory :my-documents)
(win:special-windows-directory :personal)))Generic Function, cg package
Arguments: object
Returns a symbol indicating how text is aligned horizontally in the cells of a grid-column or in a scrolling-static-text widget. The value may be set at creation time by passing the horizontal-justification initarg, or any time later by calling (setf horizontal-justification). The value may be :left, :center, or :right. The default value is :left.
For grid-widget cells, the default cell-horizontal-justification method will use this grid-column property, but a custom cell-horizontal-justification method may override it.
Generic Function, cg package
Arguments: grid-column
Returns the default cell-horizontal-padding for the cells of a grid-column. The value may be set at creation time by passing the horizontal-padding initarg, or any time later by calling (setf horizontal-padding). The value should be a non-negative integer. The default value is 2.
The default cell-horizontal-padding method will use this grid-column property, but a custom cell-horizontal-padding method may override it.
Function, cg package
Arguments:
Returns the thickness of horizontal scroll bars placed on certain windows and controls by the operating system.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the horizontal-spacing property of a chart-legend. The value may be set at creation time by passing the horizontal-spacing initarg, or any time later by calling (setf horizontal-spacing).
The minimum spacing, measured in pixels, between columns of chart objects in the chart-legend of a chart-widget. The value should be a non-negative integer. The default value is 20.
This property is used only when the draw-legend property of the chart-widget is true.
See also layout-orientation.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: class-grid
Returns whether the user can interactively scroll a class-grid horizontally, to bring other grid columns into view. This works by internally setting the scrollbars property of the body column-section to true.
The value may be set by passing the horizontally-scrollable initarg to make-instance when creating the class-grid, or by calling (setf horizontally-scrollable) later. The default value is true.
Function, cg package
Arguments: name window
Finds and returns a hotspot on a window, given the hotspot's name and the window.
Generic Function, cg package
Arguments: hotspot
Returns a value that specifies the region in which a hotspot is active, meaning where the hotspot will respond to mouse clicks and mouse movement. The value contains coordinates in the parent window's stream coordinate system.
The value may be specified by passing a :region initarg to make-instance when creating the hotspot, and/or by calling (setf hotspot-region) any time later.
The value may specify an orthogonal box, a polygon, a circle, or a line, and the format of the value depends on which type of geometrical object is being specified. Here is the format for each type:
To specify an orthogonal rectangle, the hotspot-region should be a box instance, as created with make-box, and as you might pass to draw-box or fill-box to draw a box in that location. The function inside-box-p will be called internally to determine when the mouse is in the hotspot-region.
To specify a polygon, the hotspot-region should be either a vector or a list of three or more position instances (created with make-position), as you might pass to draw-polygon or fill-polygon. The function inside-polygon-p will be called internally to determine when the mouse is inside the hotspot-region.
To specify a line, the hotspot-region should be a list of two positions for the endpoints of the line, as you might pass to draw-line. The function on-line-segment-p will be called internally to determine when the mouse is inside the hotspot-region. The mouse is considered to be in the region if the mouse is within 4 pixels of the theoretical line, since 4 is the default value of the margin argument to on-line-segment-p.
To specify a circle, the hotspot-region should be a list of a position (as made by make-position) followed by a positive integer, where the position denotes the center of the circle and the positive integer its radius. The function inside-circle-p will be called internally to determine when the mouse is inside the hotspot-region.
In releases prior to 7.0, this function was a method on box. That method still exists (along with the :box initarg) for compatibility.
Function, cg package
Arguments: window
Returns the hotspot that is currently under the mouse cursor, or nil if none. Use of this function is deprecated because it just computes the value that is always cached as current-hotspot. Call current-hotspot instead.
Generic Function, cg package
Arguments: hotspot-mixin
Returns a list of hotspots on the argument, which must be a window which can hold hotspots.
Generic Function, cg package
Arguments: &key (class 'html-browser) (html-widget-class 'html-widget-for-browser) (name :html-browser) (owner (screen system)) (child-p t) exterior (title "HTML Browser") (include-status-bar t) (title-bar t) (resizable t) (state :normal)
This is a convenience function to return a single html-browser dialog for a particular owner. If an html-browser has already been created for the specified owner (a window or the screen), and it still exists, then it is simply returned; otherwise a new html-browser is created using the various arguments to this function, and returned.
All of the arguments are simply passed to make-window, and you could alternately call make-window with the same arguments to always make a new browser. The arguments are all standard make-window arguments except for html-widget-class and include-status-bar. Refer to make-window for the others.
html-widget-class is the name of the class to instantiate for the html-widget that will be created inside the dialog. If you want to add methods for the html-widget, then you can subclass html-widget or (more likely) html-widget-for-browser and pass the name of the subclass to this function (or to make-window).
If include-status-bar is true, then the html-browser will include a common-status-bar at the bottom. Some of the default callback methods will show messages there, such as progress messages while downloading a web page. This argument defaults to t to include a common-status-bar.
See the html-browser control.
Generic Function, cg package
Arguments: html-browser
Returns a list of URI strings of the pages that the specified html-browser has visited so far. This list is taken from the range of the combo-box that is on the specified html-browser. This list could be setf'ed if desired to modify the combo-box's range.
See the html-browser control.
Generic Function, cg package
Arguments: html-browser
Returns the maximum number of URI's that will be collected in the history combo-box of the specified html-browser. Once the history has reached this maximum, older entries will be removed as new pages are visited and added to the list.
The value may be changed with setf and this function. The default value is 24.
See the html-browser control.
Generic Function, cg package
Arguments: html-widget
Returns true if there is a previous page in the chain of recently-visited pages of the specified html-widget, to which you could return by calling html-widget-go-back.
Implementation note: there appears to be no way to implement this function on Windows, and it may not be working properly on Linux, so this function may go away. The function was intended to indicate whether a Go Back button should currently be enabled.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
Returns true if there is a following page in the chain of recently-visited pages of the specified html-widget, to which you could return by calling html-widget-go-forward.
Implementation note: there appears to be no way to implement this function on Windows, and it may not be working properly on Linux, so this function may go away. The function was intended to indicate whether a Go Forward button should currently be enabled.
See the html-widget control.
Generic Function, cg package
Arguments: widget command enabled?
This generic function is called whenever the state of an html-widget has changed such that one of the typical HTML-browsing commands should be enabled or disabled.
For example, if the user moves to the previous page and there is no further previous page after that, then this function will be called to tell you that the "Go Back" command should now be disabled. Your application could add a method to this generic function to disable whatever "Go Back" button it may have. The default method calls the html-widget's on-command-change function if it has one, so the application could instead attach an on-command-change function to an individual html-widget instance.
There is also a built-in method for the html-widget-for-browser subclass, which is used in html-browser dialogs, that modifies the html-browser's toolbar buttons as needed. So if you use an html-browser dialog, you should not need to write any html-widget-command-change methods (or supply any on-command-change functions), whereas if you use the lower-level html-widget control from scratch then you likely will.
html-widget is the html-widget whose state has changed.
command is one of the keyword symbols :back, :forward, or :cancel.
enabled? is true if the specified command should currently be enabled.
The :back and :forward commands refer to whether there are further pages in the linear chain of recently-visited pages, indicating whether any "Go Back" and "Go Forward" commands should currently be enabled.
The :cancel command refers to whether a page is currently being downloaded, indicating whether any "Cancel" command should be enabled. enabled? is passed as true when a download is beginning, and as nil when it has finished.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
Copies selected text in the argument html-widget and places it on the clipboard (see *clipboard*).
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
Displays the previous page, if any, in the chain of recently-visited pages of the specified html-widget. Does nothing if there is no back page. The Back button in an html-browser dialog will call this function, or you could make your own widget that calls it.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
Displays the following page, if any, in the chain of recently-visited pages of the specified html-widget. Does nothing if there is no forward page. The Forward button in an html-browser dialog will call this function, or you could make your own widget that calls it.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget uri-string
This generic function is called when an html-widget has finished downloading a web page or loading a file. The default method calls the widget's on-new-document function if it has one, and otherwise does nothing. An application could add methods for an html-widget subclass.
html-widget is the html-widget that loaded the page.
uri-string is the URL of the web page that was downloaded, or the URI string for a file that was loaded (such as "file:///c:/dummy.txt").
An html-browser uses this generic function to display the URI in its status-bar if it has one, and also to add the URI to the history list in the dialog's combo-box. An application that uses an html-widget by itself could do similar things.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
This generic function is called when the user clicks on a link that requests that a new browser window be made. It should return true to allow the new window to be made, or nil to disallow it.
The default method will call the widget's on-new-window function if it has one, returning what it returned, and otherwise will do nothing. An application could add methods for a subclass of html-widget.
html-widget is the html-widget that is requesting a new window.
When allowing the new browser to be made, currently on Linux the return value needs to be a new html-widget that you have created, whereas on Windows the return value may be any non-nil value to indicate whether the control is allowed to make a new Internet Explorer window itself.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget message
This function is not useful. It was implemented only on the GTK version of CG, which is no longer supported.
Generic Function, cg package
Arguments: html-widget
Prints the contents of the argument html-widget.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget current max
This generic function is called a number of times while an html-widget is downloading a web page or loading a file. An application could add methods for a subclass of html-widget, typically to provide a visual indication of progress while loading the page.
The default method will call the widget's on-progress function if it has one, and otherwise will do nothing.
html-widget is the widget that is doing the downloading.
current is the number of bytes that have been downloaded so far.
max is the total number of bytes in the page being downloaded.
See the html-widget control.
Generic Function, cg package
Arguments: widget &key bypass-cache bypass-proxy
Refetches the currently displayed page of the specified html-widget from its web site or file. The Reload button in an html-browser dialog will call this function, or you could make your own widget that calls it.
The keyword arguments were used ony in the GTK version of CG, which is no longer supported.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
Saves the contents of the argument html-widget to a file (after prompting for a path if necessary).
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
Interrupts the current downloading of a web page or the loading of a file, if such a thing is currently happening, and otherwise does nothing. The Cancel button in an html-browser dialog will call this function, or you could make your own widget that calls it.
See the html-widget control.
Generic Function, cg package
Arguments: window &optional smallp
Returns (or sets with setf) the icon that is used to represent window. The value must be an icon handle (a non-negative integer), which is either the value of one of the built-in icons such as error-icon, a handle returned by calling extract-icon-from-file or create-icon-handle at runtime, or nil to use the default icon of the executable file (which is the Franz icon in the development Lisp).
When the icon is set to one of the built-in icons, both the large and small versions of the icon are set with one call, regardless of the value of smallp (a single handle is used for both sizes). Otherwise, a true
See cg-icons.html.
Generic Function, cg package
Arguments: icon-drawing-view
Returns the value of the icon-fill-colors property of a icon-drawing-view. The value may be set at creation time by passing the icon-fill-colors initarg, or any time later by calling (setf icon-fill-colors).
The colors that are used to draw the interior area of non-pixmap icons on a icon-drawing-view in a chart-or-plot. The value should be a sequence (list or vector) of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list returned by the following (see make-rgb for a list of predefined colors):
(list 'light-blue 'green 'light-red 'magenta 'cyan
'light-gray 'gray 'yellow)If the value is nil, then black is used to fill all icons. Otherwise, the first object in the chart-or-plot's sequence of chart-objects is drawn with the first fill color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.
This property is used only when the draw-icons property is true, the icons-filled property is t, and the icon-images property contains one or more non-pixmap elements. If icons-filled is :hollow then icons are filled with the body-background-color of the chart-or-plot. If icons-filled is :without-border, then icons are filled with the line-colors of the icon-drawing-view rather than the icon-fill-colors, because those typically darker colors look better when there are no icon borders.
See plot-widget, chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-blend* will have while filling icons in the chart or plot. See *color-gradient-blend* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :icon-gradient-blend initarg to make-instance, or any time later by calling (setf icon-gradient-blend).
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-direction* will have while filling icons in the chart or plot. See *color-gradient-direction* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :icon-gradient-direction initarg to make-instance, or any time later by calling (setf icon-gradient-direction).
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-filling* will have while filling icons in the chart or plot. See *color-gradient-filling* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :icon-gradient-filling initarg to make-instance, or any time later by calling (setf icon-gradient-filling).
Generic Function, cg package
Arguments: chart-or-plot
This property has an effect only on the Windows platform.
This property of chart-widget and plot-widget determines the value that *color-gradient-intensity* will have while filling icons in the chart or plot. See *color-gradient-intensity* for an explanation of its effect and the valid values.
The value can be set at creation time by passing the :icon-gradient-intensity initarg to make-instance, or any time later by calling (setf icon-gradient-intensity).
Generic Function, cg package
Arguments: icon-drawing-view
Returns the value of the icon-images property of an icon-drawing-view. The value may be set at creation time by passing the icon-images initarg, or any time later by calling (setf icon-images).
The images that are used as icons for an icon-drawing-view in a chart-or-plot. The value should be a sequence (list or vector) where each element is either a pixmap, or the symbol name of a pixmap that has been cached by calling cache-pixmap, or else the name of one of the built-in non-pixmap icons. The default value is the list (:circle :square :triangle :diamond), which is a list of all of the non-pixmap icons except for :dot.
When a pixmap is used as an icon, it is drawn at its natural size and centered about the data point that it represents. Pixmap icons look better when they have masks so that they do not make a rectangular area of the graph totally opaque; see cg-pixmaps.html for how to define pixmaps with masks.
When the name of a built-in non-pixmap icon is used as an icon, it should be one of the keyword symbols :circle, :square, :triangle, :diamond, or :dot. These icons are line drawings that can be scaled with the icon-sizes property, and are drawn according to the icon-line-widths, icons-filled, and icon-fill-colors properties.
If this property value is nil, then no icons are drawn. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first icon, the second object with the second icon, and so on. If there are fewer icons in the list than there are chart-objects, then the drawing code will cycle back through the list of icons as needed.
This property is used only when the draw-icons property is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: list-view-item
Returns (or sets with setf) a non-negative integer or nil, indicating the main pixmap (if any) to display in the argument list-view-item. If an integer, the value is an index into the large-image-list or small-image-list of the list-view widget that the argument list-view-item is on. A list-view's current layout-style determines which image-list is used at any given time.
Zero indicates the first pixmap in the list. No main pixmap is displayed in this list-view-item if the icon-index is nil or an integer greater than or equal to the number of pixmaps in the large-image-list or small-image-list, or if the large-image-list or small-image-list is nil. See also state-icon-index.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the icon-line-length property of a chart-legend. The value may be set at creation time by passing the icon-line-length initarg, or any time later by calling (setf icon-line-length).
The length, measured in pixels, of the line for each chart object in the chart-legend of a chart-widget. The value should be a positive integer. The default value is 24.
Sample lines will be drawn in the legend only when the chart-view of the chart-widget is :line to display a line-graph-view. Other attributes of the sample line will be taken from various line-graph-view properties. The icon-line-length should be large enough to make the style of the line clear, especially when the sample includes an icon due to the draw-icons property of the line-graph-view being true.
This property is used only when the draw-legend property of the chart-widget is true
See also layout-orientation.
See chart-widget and also .
Generic Function, cg package
Arguments: icon-drawing-view
Returns the value of the icon-line-widths property of a icon-drawing-view. The value may be set at creation time by passing the icon-line-widths initarg, or any time later by calling (setf icon-line-widths).
The line thicknesses that are used to draw non-pixmap icons on a icon-drawing-view in a chart-or-plot. The value should be a sequence (list or vector) of positive integers. The default value is a list of the number 1.
If the value is nil, then all non-pixmap icons are drawn with a line-width of 1. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first line width, the second object with the second width, and so on. If there are fewer values in the list than there are chart-objects, then the drawing code will cycle back through the list of line widths as needed.
This property is used only when the draw-icons property is true, the icons-filled property is nil or :hollow, and the icon-images property contains one or more non-pixmap elements. (A line-width of 1 is always used for non-hollow filled icons.)
See plot-widget, chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the icon-size property of a chart-legend. The value may be set at creation time by passing the icon-size initarg, or any time later by calling (setf icon-size).
The size that is used to draw non-pixmap icons in the chart-legend of a chart-widget. The value should be a non-negative integer. The default value is 4.
For a line-graph-view, this value is handled in the same way as each value in the icon-sizes property of a line-graph-view. See icon-sizes for more information. This chart-legend property is provided to allow the icons to be a different size in the legend than in the line graph body. The other attributes of the legend's icons will be taken from the properties of the line-graph-view, to match the line graph itself.
For a bar-chart-view, this value is used as half of the width and height of a simple square that is drawn to show the bar style of each chart object.
This property is used only when the draw-legend property of the chart-widget is true.
See also layout-orientation.
See chart-widget and also .
Generic Function, cg package
Arguments: icon-drawing-view
Returns the value of the icon-sizes property of a icon-drawing-view. The value may be set at creation time by passing the icon-sizes initarg, or any time later by calling (setf icon-sizes).
The sizes that are used to draw non-pixmap icons on a icon-drawing-view in a chart-or-plot. The value should be a sequence (list or vector) of positive integers. The default value is a list of the number 4.
Each non-pixmap icon is drawn centered about its data point and extending outward from this center point by (approximately) the specified number of pixels in each direction. The size value can therefore be thought of as the "radius" of the icon. An exception is that for the built-in :dot icon, the value indicates the "diameter" of the icon (though the :dot icon is actually square). This is to allow dots that are 1 (or 3 etc.) pixels across, especially in a plot-widget where small dots may be needed.
If this property value is nil, then all non-pixmap icons are drawn with a size of 6. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first icon size, the second object with the second size, and so on. If there are fewer sizes in the list than there are chart-objects, then the drawing code will cycle back through the list of sizes as needed.
This property is used only when the draw-icons property is true and the icon-images property contains one or more non-pixmap elements.
See plot-widget, chart-widget, and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the icon-spacing property of a chart-legend. The value may be set at creation time by passing the icon-spacing initarg, or any time later by calling (setf icon-spacing).
The distance, measured in pixels, between an icon and its label in the chart-legend of a chart-widget. The value should be a non-negative integer. The default value is 4.
This property is used only when the draw-legend property of the chart-widget is true.
See also layout-orientation.
See chart-widget and also .
Generic Function, cg package
Arguments: icon-drawing-view
Returns the value of the icons-filled property of a icon-drawing-view. The value may be set at creation time by passing the icons-filled initarg, or any time later by calling (setf icons-filled).
A value indicating whether and how the non-pixmap icons of a icon-drawing-view in a chart-or-plot are filled. Here are the possible values:
nil - Non-pixmap icons are not filled. They are simple line drawings using the icon-line-widths and line-colors of the icon-drawing-view. Overlapping parts of the chart can be seen "through" the icons.
t - Non-pixmap icons are filled using the icon-fill-colors of the icon-drawing-view, and with 1-pixel-thick black borders. This is the default value.
:hollow - Non-pixmap icons are filled with the body-background-color of the chart-or-plot, with borders drawn in the line-colors of the icon-drawing-view.
:without-border - Non-pixmap icons are filled with the line-colors of the icon-drawing-view, and no borders are drawn. The line-colors are used for filling because they are typically darker and therefore work better on a light background when there are no borders.
This property is used only when the draw-icons property is true.
See plot-widget, chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: menu-item
This function is deprecated. The methods for dialog-item and timer should not be needed by applications, and name should be used instead for header-info and tab-info.
For a dialog-item or menu-item, returns an arbitrary number assigned by the OS to the object to uniquely identify it. This number is not normally needed by a common graphics application.
For a tab-info or header-info, returns (or sets with setf) an arbitrary symbol that is used to uniquely identify the item among the items on its control. It is recommended that the function name be used in place of id, since name is now intended to work with any arbitrary object, though id remains for backward compatibility.
For a timer object, returns the unique id (which is not setf'able). id is a property of the timer class.
Function, cg package
Arguments:
When *use-alternate-websocket-nudge* is true, calling this function in CG/JS mode will idle without consuming CPU until the next event has been received from the web browser, allowing the event to be dispatched to a CG process when that otherwise might not happen during a busy loop.
It may make some custom dragging loops smoother in CG/JS mode if you bind *use-alternate-websocket-nudge* to true around the loop and call this function inside the loop.
Generic Function, cg package
Arguments: cg-configuration
If the value of this Common Graphics configuration option is true, as it is by default, then an incoming mouse movement message will not call mouse-moved if the mouse cursor has apparently not really moved.
Specifically, if the window and the X and Y coordinates of the message are the same as in the previous mouse movement message, then mouse-moved is called only if the value of this option is nil.
This may avoid a problem in certain anomalous situations, such as a reported one where a continuous stream of mouse movement messages can arrive when the Emacs-Lisp Interface (ELI) is running.
cg-configuration should be a configuration object such as returned by configuration (typically (configuration *system*)).
Function, cg package
Arguments: image-list
This function returns true if and only if the argument image-list is currently open. Currently Common Graphics uses image-lists only for list-view controls, which automatically open their image-lists when needed, so this function is not likely to be needed by applications.
Note that if a list-view control that does not have the share-image-lists property turned on is removed from its dialog or the dialog is closed, then the operating system will destroy any image lists that were used by the list-view control. An application can call image-list-open-p to determine whether this has happened. On the other hand, close-image-list is not called when the OS destroys an image-list, and so an application cannot check for this occurrence by wrapping close-image-list, and should call image-list-open-p instead.
See list-view.
Function, cg package
Arguments: path
Dynamically loads a JavaScript code file at run time, which allows integrating pre-existing JavaScript code with a CG/JS application that's written in Lisp. Then the CG function call-js can be called in Lisp to call JavaScript functions that are in that file.
path is a pathname or path namestring of the file to import. The file will be imported by first publishing the file with AllegroServe, and then importing it in the JavaScript code with the import function. The call to this function will return only after the import has completed, and so calls to imported functions should work immediately after that.
For a JS function to be callable after importing the file, it must be exported. A single export statement could be added at the end of the JS file (for example) for exporting everything that should be callable from Lisp:
export { doSomething, doSomethingElse };When developing a project in the IDE, a convenient alternative is to set the JavaScript Files to Import option on the CG/JS tab of the of the Project Manager dialog. Then running the project will call this function automatically to load the JS files. And generating the standalone application will copy the JS files to the distribution, and this function will be called to load those files when running the application.
Function, cg package
Arguments: directory output-file &key make-masks filenames
Converts a set of .bmp pixmap files into a new file of Lisp source code. This is useful for building the pixmaps into the single image file of a delivered application, without needing to distribute the .bmp files themselves.
directory is a pathname or path namestring that names a directory containing one or more .bmp files to convert. (When a namestring, the final slash is optional.)
output-file is a pathname or path namestring that names a Lisp source code file that will be created and contain generated Lisp source code that creates the pixmaps. If a file already exists at this path, then it is replaced, so take care not to inadvertently destroy a needed file.
If make-masks is true, then generate-mask will be called on each pixmap so that the generated code creates a mask for each pixmap. The transparent-pixel-value passed to generate-mask will be nil, so the masks will be based on the upper-left pixel of each pixmap.
If filenames is nil or unspecified, then all of the .bmp files in the specified directory will be included. Otherwise it should be a list of strings which are the pathname-names of a subset of the directory's .bmp files to include.
The name of each pixmap in the generated code will be a keyword symbol whose name is the pathname-name its .bmp file, converting any spaces in the filename to dashes. The generated code also calls cache-pixmap on each pixmap that it creates, so that each one can be found at run time by calling find-pixmap on its name.
A similar effect can be achieved by calling load-pixmap and then calling recreation-code on the returned pixmap, but import-pixmaps makes this process more convenient.
Macro, cg package
Arguments: (&key process-name exit-test) &body body
Creates a new Common Graphics process that executes body and then calls event-loop. The window argument that is passed to event-loop will be the first value that was returned by the body if it is an open window, and otherwise will be nil. exit-test will be passed straight through to the call to event-loop. process-name will be the name of the process if one is passed, and otherwise a gensym'ed string beginning with "CG Process" will be used. in-cg-process returns the process that was created, which will later exit when its call to event-loop exits in its usual way.
This macro also passes *default-cg-bindings* as the initial-bindings argument to process-run-function, as described in About using multiple windowing threads in a Common Graphics application in cgide.html.
This macro is particularly convenient when testing Common Graphics code in a Lisp that does not include the IDE, because creating windows and then calling event-loop directly in a console or Emacs listener would tie up the listener until the call to event-loop exits. This is not an issue in the IDE where the IDE listeners manage their own Common Graphics event loops.
in-cg-process works only when Common Graphics has been initialized by calling initialize-cg (which is done automatically by the IDE and by any standalone application that was created from an IDE project using standard IDE tools but might not be done in other applications).
As a trivial example, the following will create a window in a new process that exits when the window is closed, due to the returned window being passed to event-loop internally:
(in-cg-process (:process-name "Simple Test")
(make-window :foo
:class 'frame-window
:exterior (make-box-relative 200 200 300 200)
:title (format nil "In process ~a"
(mp:process-name mp:*current-process*))))Generic Function, cg package
Argumentstray-item:
Returns true if tray-item is currently in the system tray, and returns nil otherwise. tray-item must be an instance of the tray-item class. The item is in the tray if add-tray-item has been called on it more recently than remove-tray-item has.
See the description of the tray-item class for an example.
Generic Function, cg package
Arguments: object-editor
Returns whether an object-editor dialog includes a special class-grid at the bottom that lists all of the edited-instances of the dialog. The value may be set at creation time with the include-table-of-all-instances initarg or any time later by calling (setf include-table-of-all-instances). Toggling this value after creating the object-editor would create or delete the table and adjust the bottom of the dialog to make the included widgets just fit. The height of the class-grid will be the value of the layout-all-instances-table-height property.
When the table is included, it includes a grid column for each slot-editing widget that's on object-editor, using the same type of editing. The user may then edit instances in either the all-instances table or in the other widgets. Selecting a row in the all-instances table calls display-instance to display the instance of that grid row in the main part of the object-editor dialog.
This feature may be unwieldy if there are many edited instances.
Generic Function, cg package
Arguments: scroll-bar-mixin
Returns the value of the increment property of its argument. This property is a numeric (fixnum) value relating to the range of the object. For instance, if the range is (0 100) and the increment is 1, then pressing an arrow key will advance the control's slider bar 1/100 of the way across the dialog in that arrow's direction.
increment is a property of the up-down-control, trackbar, horizontal-scroll-bar, and vertical-scroll-bar classes.
For an up-down-control, alternate values are allowed to determine how the control continues to increment as the user holds down the mouse button after clicking on an arrow. In particular, if the value is an association list of non-negative integers of the form ((elapsed-seconds increment) (elapsed-seconds increment) ...), then the increment will change at various points in time. For example, a value of ((1 1)(1 3)(2 10)(4 100)) indicates that the up-down-control should increment (or decrement) by 1 for the first second, by 3 for the next second, by 10 for the next 2 seconds, and then by 100 thereafter until either the mouse button is released or the maximum or minimum value of the control's range is reached. If the value is instead a single integer, then the control will continue to increment by that single amount. The default value is nil, which means to use the default increment pattern.
Generic Function, cg package
Arguments: calendar-widget
The name of the upper-right pixmap for displaying the next page in a calendar widget. The pixmap needs to be cached with cache-pixmap in order for the widget to find it from this name.
See also decrement-pixmap-name, the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: outline
Returns the value of the indentation property of the argument. This property specifies the number of pixels subitems are indented.
indentation is a property of the outline and dropping-outline classes.
Generic Function, cg package
Arguments: tab-info
Returns the index of the argument. Thus, for a tab-info object, returns where it appears in the parent tab-controls range with numbering starting at 1.
Generic Function, cg package
Arguments: outline item
Returns as multiple values the index level and parent-item of item, which should be an item of outline.
Generic Function, cg package
Arguments: outline item-value &key (key #'identity) test only-after-index
Returns the multiple values (index level item parent-item) for an item value. If not found, returns four values, all of which are nil.
Function, cg package
Arguments: box dx dy
Modifies and returns box by subtracting dx from its left, and adding it to its right; and subtracting dy from its top, and adding it to its bottom. The result, which is returned, is a box (* 2 dx) wider and (* 2 dy) higher. dx and dy must be fixnums. This function is effectively equivalent to
(setq box
(nmake-box box
(- (box-left box) dx) (- (box-top box) dy)
(+ (box-right box) dx) (+ (box-bottom box) dy)))See the description of the box class and make-box for information on boxes. See nmake-box, which modifies an existing box rather than creating a new one.
Function, cg package
Arguments:
Returns a pre-defined icon to accompany an informational message to the user. In CG/JS mode this is actually a pixmap, which can be used as an icon in that mode. In Windows desktop mode it is the icon that is the value of the information-icon variable.
Generic Function, cg package
Arguments: window
If this generic function returns true for a particular window, then tracing (see trace and debugging.html) will be suppressed for code that runs in event-handling callbacks for that window. This could be useful for eliminating extraneous trace output that would otherwise be generated for tool windows that you are not testing.
There are various built-in methods for certain windows (and other internal objects) that avoid the cases where this is usually needed (such as inhibiting trace output while updating the IDE's trace dialog), but perhaps some users would find it useful to add additional methods.
Generic Function, cg package
Arguments: property
Returns the initarg name that can be used to set the initial value of a property when creating an instance the class of which property is a property. Instances are created with make-instance and with some specialized make- functions such as make-window.
The function properties returns the properties (those displayed on the Properties pane of the Inspector when the object is being inspected) of an object or a class. The function event-handlers returns the event handling properties (displayed on the Events pane of the inspector). Items from either list are suitable as an argument to this function.
Generic Function, cg package
Arguments: html-browser
Returns a list of URI's that should be used as the initial history list in a newly-created html-browser. The default method returns nil.
The IDE's help window adds a method on its html-browser subclass so that it can restore a history list that was saved in the previous Lisp session. An application could add a similar method for its html-browser subclass if desired.
See the html-browser control.
Function, cg package
Arguments:
This function has been renamed initial-pixmap-color-vector. The new name does not use `palette' in reference to a pixmap. (Windows have palettes which are very different from a pixmap color vector.) The functionality of initial-pixmap-color-vector is identical to the (prior to release 7.0) functionality of this function. Please use initial-pixmap-color-vector instead of this function. The function remains for backward compatibility only.
Function, cg package
Arguments:
This function is not intended for use by applications. It is exported because the code that is automatically generated for a form window calls it for internal reasons. Applications should call default-pixmap-color-vector instead.
This function replaces the function initial-palette-vector, which is now deprecated.
Function, cg package
Arguments:
Initializes Common Graphics. This function needs to be called before any other Common Graphics functions are called. This is done automatically by the IDE, and by any standalone application that was created from an IDE project with the File | Build Project Executable or File | Build Project Distribution commands (unless the project does not use the default on-restart function, which is not normally changed). You should need to call initialize-cg only in a Lisp that does not have the IDE running (see ide:start-ide) or in a standalone application that was created with a direct call to generate-application.
If Common Graphics is already initialized, initialize-cg simply returns the process that initialized it. Otherwise it attempts to initialize Common Graphics, and returns t if this was successful and nil if not. The value of *cg-is-initialized* indicates whether Common Graphics is currently initialized.
initialize-cg needs to be called only a single time even when multiple Common Graphics processes are used. The only processes that may use Common Graphics functionality are the ones that called initialize-cg plus any other processes that are created later by passing *default-cg-bindings* as the initial-bindings keyword argument to process-run-function (see About using multiple windowing threads in a Common Graphics application in cgide.html). In either case, the process typically will then create one or more windows (see make-window) and other Common Graphics objects and then call event-loop to handle events. The macro in-cg-process may be used to handle the process creation and calling of event-loop for a body of Common Graphics code.
When loading individual Common Graphics modules into a development Lisp where the IDE is not loaded, all modules that are to be used should be loaded before calling initialize-cg. If additional modules need to be loaded later, first call exit-cg, then load the modules, and then call initialize-cg again.
Common Graphics may be loaded in its entirety into a base Lisp by simply evaluating (require :cg). To instead load a subset of the many Common Graphics modules, you could require or load any of the modules in Allegro's code/ subdirectory that begin with cg-. Each Common Graphics module will automatically load other modules on which it depends.
Generic Function, cg package
Arguments: dialog-item new-value
Changes the value of the control specified by the dialog-item argument. Differs from (setf value) in that the on-change event handler is not run when the value is changed with initialize-value and is run when it is changed with (setf value).
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the inner-horizontal-margin of the argument lamp. This is the horizontal pixel distance between the lamp image and the title string of a lamp widget (when the title-side is :left or :right), or between the multiple lamp images when the value property is an array.
See the description of the lamp control.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the inner-vertical-margin of the argument lamp. This is the vertical pixel distance between the lamp image and the title string of a lamp widget (when the title-side is :top or :bottom), or between the multiple lamp images when the value property is an array.
See the description of the lamp control.
Generic Function, cg package
Arguments: text-edit-pane character
Programmatically inserts the specified character into text-edit-pane at the current text cursor position, just as if the user had typed that character.
text-edit-pane should be a text-edit-pane and character should be a Lisp character.
Generic Function, cg package
Arguments: *window-or-widget *
Retrieves an object from the clipboard and inserts it into the specified window or widget.
This function behaves just as paste-command does except that it calls insert-selection rather than paste-selection so that any selected content is retained rather than replaced. See paste-command for more information.
See cg-clipboard.html.
Generic Function, cg package
Arguments: window-or-widget object
Adds object to the current content of window-or-widget if it knows how to do so, generally at the "current position" in the window or widget. If an insertion is done, then object is returned as the first returned value and a clipboard format is returned as the second value; otherwise nil is returned. This function is called by insert-command, which grabs object off of the clipboard to pass to this function.
This function behaves just as paste-selection does, except that any currently selected content is retained instead of being replaced by the inserted content. See paste-selection for more information.
See cg-clipboard.html.
Function, cg package
Arguments: position box
Returns true if position is inside box. Positions on the borders of the box are included. Returns nil if position is not inside box.
Function, cg package
Argumentsposition center-position radius:
Returns whether position is inside the circle that is defined by center-position and radius. position should be a position instance (as created with make-position), center-position should be a position that specifies the center of the circle, and radius should be a positive integer that specifies the radius.
This function is used internally by circular hotspots (see hotspot-region), but can be used by itself if desired.
Function, cg package
Arguments: process
Returns true if the specified process is currently inside a call to event-loop, and returns nil otherwise. It is OK to specify a dead process, in which case nil is returned.
In a Common Graphics application, a process normally should always be inside a call to event-loop if it needs to be handling messages that are sent to windows that are created in that process.
See exit-event-loop.
Function, cg package
Argumentsposition position-vector-or-list:
Returns whether position is inside the polygon that is defined by position-vector-or-list. position should be a position instance (as created with make-position), and position-vector-or-list should be either a vector or a list of positions that define a polygon, just as you would pass to draw-polygon or fill-polygon.
The beginning position should not be repeated at the end of the vector or list to "close" the polygon, and so a vector or list of three positions would specify a triangle. A position that is exactly on a line segment is considered to be "inside" the polygon.
This function is used internally by polygonal hotspots (see hotspot-region), but can be used by itself if desired.
Function, cg package
Arguments: integer
Returns four integer values indicating the track, minute, second, and frame of an mci time such as would be returned, for example, by mci-device-position, assuming that the time-format of the device is :tmsf.
For finer control over device operation, various optional keyword arguments are provided by the methods. For example, to play the first minute of the third track on the cd:
(mci-device-set-time-format cd :tmsf)
(mci-play cd :from (tmsf-to-integer 3 0 0 0)
:to (tmsf-to-integer 3 1 0 0)The above code first tells the device to use the track-minute-second-frame (:tmsf) time format for describing its current location, and then tells the CD to play from "track 3 minute 0" to "track 3 minute 1". (The function tmsf-to-integer is required because there are various time formats that use different numbers of components.) To determine the current position of the CD device while it is playing, use:
(multiple-value-setq (track minute second frame)
(integer-to-tmsf (mci-device-current-position cd)))See cg-mci.html for information about MCI support in Common Graphics.
Function, cg package
Arguments: window-or-screen
Returns the interior (a box object, see make-box) of window-or-screen. The box is relative to the upper-left corner of the "page" of the parent window, or of the screen if there is no parent window. (A "page" is the logical canvas of a window, on which drawing is done and which is sometimes scrollable. So if the parent window is not scrolled, then the box is relative to the upper-left corner of the parent's interior.) The unit of measurement is pixels.
The screen is the value returned by (screen *system*). See screen and *system*. For the screen, the interior is the area that excludes the taskbar.
See also ninterior.
Generic Function, cg package
Arguments: window-or-screen
Returns the height of the interior of window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*. For the screen, the interior is the area that excludes the taskbar.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the interior-horizontal-margin property of a chart-legend. The value may be set at creation time by passing the interior-horizontal-margin initarg, or any time later by calling (setf interior-horizontal-margin).
The horizontal distance, measured in pixels, between the border of a chart-legend in a chart-widget and the contents of the legend. The value should be a non-negative integer. The default value is 10.
This property is used only when the draw-legend and draw-legend-border properties of the chart-legend are both true.
See also interior-vertical-margin and layout-orientation.
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments: window-or-screen
Returns as a position object the top-left corner of the interior of window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*. For the screen, the interior is the area that excludes the taskbar.
See also ninterior-top-left.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the interior-vertical-margin property of a chart-legend. The value may be set at creation time by passing the interior-vertical-margin initarg, or any time later by calling (setf interior-vertical-margin).
The vertical distance, measured in pixels, between the border rectangle of a chart-legend in a chart-widget and the contents of the legend. The value should be a non-negative integer. The default value is 3.
This property is used only when the draw-legend and draw-legend-border properties of the chart-legend are both true.
See also interior-horizontal-margin and layout-orientation.
See chart-widget and also .
Generic Function, cg package
Arguments: window-or-screen
Returns the width of the interior of window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*. For the screen, the interior is the area that excludes the taskbar.
Generic Function, cg package
Arguments: timer
This function returns a positive integer indicating the number of milliseconds after a timer is started that it will "fire" by calling the generic function timer. The default timer method calls the timer's individual on-timer function (if it has one), which is where timer messages are usually handled by an application. If the interval property is modified while a timer is active, then the timer is stopped and immediately restarted using the new interval. The interval default-initarg for the timer class is 1000, which will fire the timer once a second.
interval is a property of the timer class. setf may be used with this function to change the interval for a timer.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: object &key (interior t) frame children box (erase t)
Invalidates object so that redisplay-window will be called automatically to redraw the invalidated area. redisplay-window will be called only when there are no more queued events, which reduces flashing by redrawing an object only once even if it has been invalidated multiple times while handling a sequence of events. See also update-window.
object may be a window, dialog-item, outline-item, or hotspot, though the keyword arguments are used only by windows (including the associated widget-window when a dialog-item is passed).
The first three keyword arguments specify what is invalidated: the interior (client area), the frame (or border), and/or the child windows if any. interior defaults to true, while frame and children default to nil.
box specifies what part of the interior to redraw, when interior is true. If box is nil, as it is by default, then the entire visible-box of the window is redrawn (or the entire page-box in web browser mode if draws-the-entire-scrolling-page returns true). Otherwise box should be a box in the window's stream coordinates that indicates the rectangular area to redraw. This box will be passed to the redisplay-window method, which can avoid drawing anything that does not intersect this box, for efficiency. The clipping-box of the window will also be set to this box at this time, which reduces flashing even when the redisplay-window method does attempt to draw outside the box.
If erase is true, it ensures that all content is erased before being repainted, though in fact this is typically done by a window's redisplay-window method anyway.
When a hotspot is passed, the region-box of its hotspot-region is invalidated in the hotspot's parent window, to redraw the smallest rectangular area that fully contains the hotspot.
When an outline-item is passed, that individual item is redrawn instead of redrawing the entire outline.
See cg-drawing.html for a discussion of the uses of redisplay-window, invalidate, and update-window.
Generic Function, cg package
Arguments: row column &optional (row-num 0) (column-num 0) redraw-now-p data-area-only-p
Invalidates (tells the operating system that the image may be corrupted) the grid cell. The keyword arguments specify the row and column number and also whether redrawing should be immediate and whether the data area or the whole thing should be invalidated. If redrawing is not immediate, it will occur whenever the redrawing would normally be done.
Generic Function, cg package
Arguments: dialog-item &optional box erase-p
Tells the operating system to invalidate part or all of a component window, so that the operating system will tell the window to redraw itself after all other message processing has completed. If box is nil, then the entire window is invalidated; otherwise box should be a box in the component window's own coordinate system (0,0 refers to the interior top left of the component), and only that portion of the component window will be invalidated. If erase-p is true, then the operating system will be told to erase the invalidated region before it sends the message to the window to tell its event handler to redraw it.
The more general function invalidate is now recommended over most of the invalidate-* functions.
Generic Function, cg package
Arguments: dialog-item
Tells the operating system to invalidate the frame (non-client area) of a component window, so that the operating system will tell the window to redraw itself after all other message processing has completed.
The more general function invalidate is now recommended over most of the invalidate-* functions.
Generic Function, cg package
Arguments: row-section column-section &optional redraw-now-p
Tells the operating system to invalidate the grid section specified by the arguments so that the operating system will tell the grid section to redraw itself after all other message processing has completed, or immediately if redraw-now-p is true.
Though the function invalidate is now recommended over most of the invalidate-* functions, it does not replace invalidate-section.
row-section may be either a row-section or a grid-row, and column-section may be either a column-section or a grid-column. So you could, for example, invalidate the area where a single grid-row crosses a whole column-section.
See also invalidate-whole-section.
Generic Function, cg package
Arguments: grid-section-or-subsection
Invalidates whatever part of the specified grid section is currently scrolled into view so that it will be redrawn to reflect possibly updated application values. If the section is completely scrolled out of view, then nothing is done. This is more efficient than calling invalidate on the whole grid-widget if you know that changes are limited to one section.
The argument should be a grid-row-section, grid-column-section, grid-row, or grid-column.
See also invalidate-section.
Generic Function, cg package
Arguments: window &optional box erase-p
Invalidates box of window which means that it will be later repainted. box defaults to the visible-box of window. If erase-p is true (default is nil), then window's background is cleared before it is repainted.
The more general function invalidate is now recommended over most of the invalidate-* functions.
Generic Function, cg package
Arguments: window
Invalidates the frame of window. The more general function invalidate is now recommended over most of the invalidate-* functions.
Generic Function, cg package
Arguments: window
This generic function is called when a window is created. If it returns true, a flag associated with a window is set telling the Operating System to invalidate the entire window whenever it is resized. If this generic function returns nil, the flag is not set. The flag cannot subsequently be changed.
Note that this generic function is called only when a window is created (as its purpose is to set a flag at window-creation time). This means that any custom methods should exist and return the appropriate value at window creation time and, of course, programmers should not expect the methods to be run when the window is subsequently resized.
The default method returns nil, but programmers can define methods on their own window classes that return true.
For example, if a window's redisplay-window method draws a picture in the window such that it is stretched to fill the window interior, then resizing the window should require the entire picture to be redrawn. Adding an invalidate-window-on-resize method that returns true for that window's class (before any instances are created) will ensure that redisplay-window is called whenever the window is resized so that the needed redrawing is done.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the invert-axis property of a chart-axis. The value may be set at creation time by passing the :invert-axis initarg, or any time later by calling (setf invert-axis).
A boolean value indicating whether the values of a chart-axis in a chart-widget should increase in the atypical direction. The default value is nil.
The "typical" direction is defined as from bottom to top for a vertical axis or from left to right in a horizontal axis. The values of an axis whose invert-axis property is true will increase in the opposite direction. For an item-axis, this property affects the direction in which new chart items are added.
Either the value-axis or the item-axis of a chart-widget may be the vertical or the horizontal one as well; see chart-orientation.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: stream box
Inverts the pixels on stream that lie inside box. stream should be a graphical-stream. box should be a box object, as created with make-box. To use individual coordinates rather than making a box, see invert-box-x-y.
A pixel is inverted by reversing each bit in its value. If the stream is using true color, then inverting red produces cyan, for example, by turning off all of the red bits and turning on all of the green and blue bits. If the stream is using a palette instead, then the inverted color would be whatever color is found in the palette at the index that is produced by reversing the bits of the pixel's current palette index.
Generic Function, cg package
Arguments: stream left top right bottom
Inverts the pixels on stream that lie in a rectangular area from an upper-left corner at (left, top) to a lower-right corner at (right, bottom). stream should be a graphical-stream. The other arguments should be integers. To use a box object rather than individual coordinates, see invert-box.
A pixel is inverted by reversing each bit in its value. If the stream is using true color, then inverting red produces cyan, for example, by turning off all of the red bits and turning on all of the green and blue bits. If the stream is using a palette instead, then the inverted color would be whatever color is found in the palette at the index that is produced by reversing the bits of the pixel's current palette index.
Generic Function, cg package
Arguments: pixmap
Returns (or sets with setf) whether the rows of pixels in pixmap are ordered such that they would appear inverted in the printed representation of the pixmap contents. That is, if invert-p is true, it indicates that the first row in the pixmap contents is the bottom row of pixels in the actual image, though that row will appear on top when the pixmap contents are printed. invert-p does not normally need to be set by an application, since Common Graphics internally knows how to handle either mode. The default is nil, so that when the contents of a pixmap are specified as a static list of lists in Lisp source code, the source ccode will be oriented the way that the actual image would appear in a window.
Note that the Windows operating system expects the first row of pixels to be the bottom of the image, and so what Common Graphics refers to as an "inverted" pixmap is actually the most natural orientation for the OS. When invert-p is nil, Common Graphics internally tells the OS to flip the pixmap whenever it is drawn, and so it may be that a pixmap that does not use a pixmap-handle draws somewhat faster when invert-p is true. And more important, there is a bug that is apparently in Windows 95 (but not later versions of Windows) where sometimes a pixmap will not appear at all when copied to a window if the pixmap's invert-p property is nil and it does not use a pixmap handle. There is no workaround for this Windows 95 bug other than providing a handle with open-pixmap-handle or defining the pixel array so that the bottom row of pixels is the first row of the contents list (setting the invert-p property of the pixmap to true).
invert-p is a property of the pixmap class.
function, cg package
Arguments: path-or-url
This function is deprecated, and the newer function invoke-private-html-browser should be used instead. Note that that function no longer uses a "private" instance of a web browser that is used only by the Lisp application, and is now the general function to use for invoking a web browser.
On Windows, this older function uses hacks that were needed to avoid creating a new web browser window on each call, before web browsers began instead adding a new tab to the existing browser window when the program is run with another URL. That only works for particular browsers, where it looks for the name of the browser in the title bars of windows, and then it uses even worse hacks to simulate typing keystrokes into that window.
Function, cg package
Arguments: url-or-path &key (browser :explorer)
This function is essentially the old implementation of invoke-html-browser. It uses a DDE interface to invoke the browser, while the new implementation of invoke-html-browser does not use DDE. Use of this function is not recommended unless you have problems with invoke-html-browser, in which case, this function can serve as a temporary workaround until the problems with invoke-html-browser are patched. (Please contact Franz Technical Support at [email protected] to report problems with invoke-html-browser.)
This function invokes a running Internet Explorer or Netscape 4.x browser, if any, using the browser's traditional DDE interface. If the browser is found, then the requested page (specified by the url-or-path argument) is shown and true is returned; otherwise nil is returned (in which case you might want to try the other browser or revert to calling invoke-html-browser).
url-or-path may be either a complete URL (including the "http://") or the pathname or path namestring of an HTML file.
browser may be either :explorer (for Microsoft Internet Explorer) or :netscape (for Netscape 4.x). The default is :explorer.
Function, cg package
Arguments: url-or-pathname &key box waiting-title
Displays a web page or file in a web browser. url-or-pathname should be either the URL string of a web page or the pathname or path namestring of a local file to display. The keyword arguments are no longer used, and are retained only for compatibility with existing application code. If this function believes that it successfully displayed the requested page, then true is returned, and otherwise nil is returned.
If Common Graphics is already running in a web browser, then the web page or file will be shown in a new tab of that same browser. Otherwise (including when starting up a generated CG application), this function works by executing a command line that runs the default web browser application, passing the URL or file path to display. For apparently all popular web browsers, this will start the browser application if it is not already running, or else (at least by default) add a new tab to the browser that is already running.
When using a command line to invoke the default browser, the command line is found differently on different operating systems. On Windows, the function windows-command-for-document-type is called to find the path of the default web browser. On a Mac, the command line simply runs "open". On Linux, the command line will try to run "xdg-open", "gnome-open", and "firefox" in turn until if and when one of those succeeds; if none succeed, then the URL or file path will be posted to the system clipboard. You could then paste the URL into a web browser if there's one that you can run yourself.
The word "private" in this function name is an anachronism, and the function name has remained the same only for backward compatibility. The function formerly had used a "private" instance of a browser that's used only by the Lisp application, rather than displaying in an already-running browser. Now that a single browser will create a new tab, what the user had been viewing in their browser will no longer get buried by multiple URLs or files that are displayed there by Lisp.
See also private-html-browser-handle.
Generic Function, cg package
Arguments: cg-configuration
This configuration option determines how the function invoke-private-html-browser invokes a third-party HTML-browsing program on the Windows platform.
If the value of this option is true, and the platform is Microsoft Windows, and the default HTML-browsing program is either Firefox (or Mozilla or Netscape), or Google Chrome, or Internet Explorer, and an instance of that program is already running, then the function invoke-private-html-browser will invoke that running HTML browser by emulating keystrokes that enter a URL.
In all other cases, run-shell-command is used instead to invoke the program each time.
Using run-shell-command may be more robust, but it may create a new browser window each time, depending on which browser is the default HTML program and the user's preference settings in that program.
The value can be a list of browser program names to cause the keystroke approach to be used with some browsers but not others. The names in the list can include any of the following keywords: :firefox, :chrome, :explorer, :mozilla, :netscape6, and :netscape4.
The default value is a list of the symbol :explorer, to use the keystroke approach with Internet Explorer but the run-shell-command approach with other browsers. The reason is that Internet Explorer creates a new browser frame window with the run-shell-command approach (and takes a little while to do so), and does not appear to have an option to reuse a single frame window. On the other hand, the keystroke approach has become unreliable with recent versions of Firefox. Firefox can reuse a single browser frame window with the run-shell-command approach, though you may need to turn on its option found at Tools | Options | Tabs | Open new windows in a new tab instead. Google Chrome appears to always reuse a single frame window.
This option affects the showing of IDE help when the ide:use-cg-html-browser option is nil.
cg-configuration should be a configuration object such as returned by configuration (typically (configuration *system*)).
This option is not included on the IDE's Options dialog, but it could be turned off with this form:
(setf (invoke-web-browsers-with-keystrokes (configuration *system*))
nil)Compatibility note: Prior to release 8.2, the system acted as if the value was t to use the keystroke approach with all browsers. But the keystroke approach became less reliable with updates to Firefox, and so the default has been changed.
Generic Function, cg package
Arguments: window
Returns true if the specified window is allowed to have child windows.
If is-child-allowed returns nil for a window foo, and a second window bar is created with the foo specified as its parent, then bar becomes an owned window of foo rather than a child window.
This feature is used by the IDE's development-main-window to force all windows created on it to be owned. In addition, the default parent of a window created in the IDE is the development-main-window. Because of these two facts, a window created in the IDE with no parent specified becomes an owned window of the IDE's invisible development-main-window.
An application could add an is-child-allowed method for a class of window that is intended to always be an owner window rather than a parent.
See About child, parent, and owner windows in cgide.html.
Generic Function, cg package
Arguments: window
Returns true if window is currently being invoked in the current thread in a modal way, as by a window displayed with pop-up-modal-dialog.
Generic Function, cg package
Arguments: text-edit-pane
The function returns t if all of the selected range of text-edit-pane is italic, nil if it is all non-italic, and :some if there is a mix.
The setf function turns italic-ness on or off in the selected range of text-edit-pane. value is either nil to turn it off or true to turn it on.
text-edit-pane must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the item-axis property of a chart-widget. The value may be set at creation time by passing the :item-axis initarg, or any time later by calling (setf item-axis).
item-axis is the axis of a chart-widget along which a sequence of chart items is placed. The value is an instance of the item-axis class, and holds properties that determine how the axis is drawn.
The value of this property is always an item-axis instance. If you do not pass an item-axis instance as the value of the :item-axis initarg when creating a chart-widget, then a default instance is created automatically.
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments: &optional process
Returns true if and only if the specified process (which defaults to the current process) is running in CG/JS mode rather than Windows desktop mode. This could be called to determine the mode in which a user is now running your application (as long as you do not call it on a non-CG process).
Generic Function, cg package
Arguments: rich-edit-pane link
This generic function is called when the user clicks on a link that has earlier been found by find-links and cached as the links property of rich-edit-pane, which must be a rich-edit-pane. The link argument is a list of starting-index, ending-index, and the string for the link that was clicked on.
The default jump-to-link method calls pathname-for-link to convert the link string into the path of an .rtf rich text file to link to. If jump-to-link returns an existing file, then rich-edit-open is called on it to display it in the window.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: rich-edit-pane
Returns (or sets with setf) whether jumping to links is currently turned on for rich-edit-pane, which must be a rich-edit-pane. This property is on by default, but when toggled off there will be no attempt to jump to a link when it is clicked on. It may be desirable to turn this property off while editing links.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: standard-object
Returns (or sets with setf) how text will be positioned horizontally on object. The value should be one of the symbols :left, :center, or :right.
justification is a property of the list-view-column, header-info, editable-text (see note below), multi-line-editable-text, static-text, and button classes.
Note on editable-text on Windows: according to Microsoft, this option will work for a single-line text editing control (the editable-text in Common Graphics) only in Windows 2000 or later. In Windows NT 4.0 the control will presumably remain left-justified, though we have observed alternate justification working in Windows NT 4.0 Service Pack 6.
Note on text-edit-panes on Windows: If object is an instance of text-edit-pane (such as a rich-edit-pane), justification returns the paragraph justification of the selected text of the argument. The possible values are :left, :center, or :right.
The setf function for a text-edit-pane sets the paragraph justification of the selected text.
On Windows, the justification property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :resizable initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
A text-edit-pane argument must be an instance of a text-edit-pane. It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: grid-widget
Returns the value of the keep-focus-in-view property of grid-widget. That property determines whether a grid-widget will move its internal keyboard focus as needed so that it remains in view as grid sections are scrolled. The setf of this function may be called to set the value. The default is t.
If true, then whenever a section of the grid-widget is scrolled, and that section contains the current focus-cell of the grid, and the focus-cell is partly or completely scrolled out of view, then the focus-cell of the grid-widget is set to be a cell of that section that is entirely in view. (If no cell is entirely in view, then a cell that is partially in view is used instead.)
If nil, then no such action is taken.
This option facilitates navigating a grid-widget with the keyboard by first using the PageUp and PageDown keys to scroll a particular cell into view, and then using the arrow keys to move into that cell. If this option is turned off, then scrolling a grid section may leave the focus-cell scrolled far out of view, and then pressing an arrow key would scroll the grid section back to the current focus-cell. On the other hand, it may be distracting when this option is turned on to see the focus rectangle jumping around as a grid section is scrolled.
Side note: The PageUp and PageDown keys will scroll a grid section horizontally if the Control key is held down.
keep-focus-in-view is a property of the grid-widget class.
Function, cg package
Arguments: virtual-key-code
Returns two values indicating whether a particular key on the keyboard is currently depressed. The argument should be either the char-int of some graphic character or the value of one of the symbols beginning with vk-. This check is done asynchronously.
The first value indicates whether the key is down now (true if it is, nil if it is not). The second returned value indicates whether the key has been pressed since the last time this function was called.
For a letter key, the key code is the char-int of the uppercase character shown on the key (and NOT the corresponding lowercase character). For a numeral key, it is the char-int of the numeral character. For any other key, the key code is the value of the vk- constant for that key (see key-names for a list of vk- constants); for keys that show both a shifted character and an unshifted character, this constant will be named after the unshifted character.
Function, cg package
Arguments: virtual-key-code
Returns the symbol naming the virtual key associated with the argument code. Thus:
(key-name vk-pagedown) returns the symbol vk-pagedown.
Function, cg package
Arguments: virtual-key-code
Returns two values indicating whether a particular key on the keyboard was pressed at the time the event currently being handled occurred. The argument should be either the char-int of some graphic character or the value of one of the symbols beginning with vk-. This check is done asynchronously.
The first value indicates whether the key was down when the current event occurred. The second returned value indicates whether the key is toggled. A key is toggled if it has been pressed an odd number of times. For keys such as CAPS LOCK and NUM LOCK, this indicates whether the key is on.
For a letter key, the key code is the char-int of the uppercase character shown on the key (and NOT the corresponding lowercase character). For a numeral key, it is the char-int of the numeral character. For any other key, the key code is the value of the vk- constant for that key (see key-names for a list of vk- constants); for keys that show both a shifted character and an unshifted character, this constant will be named after the unshifted character.
Generic Function, cg package
Arguments: dialog-item
This generic function is called when the keyboard focus leaves a control. Applications may add kill-focus-event methods to handle this event for a whole subclass of controls as an alternative to writing individual on-kill-focus event-handler functions for each control. Applications should not call kill-focus-event.
The default method calls the on-kill-focus event-handler function of the control specified by the argument dialog-item, if it has one, and performs other internal functionality that should not be overridden.
See set-focus-event.
Function, cg package
Argumentsproject:
Looks for the "splash screen" window that might have been shown as the running standalone application was starting up, and closes it if found. Returns true if a splash window was found and closed, and nil otherwise. It may be useful to call this function when an app has finished starting up, rather than making the end user wait for the splash screen to go away after an arbitrary amount of time.
(See the descriptions of the +b, +Bt, and +Bp arguments in Command line arguments in startup.html. Those arguments control the initial display of a splash screen. +b and +Bt display the splash screen for three seconds, while +Bp displays it until the user clicks on it. kill-splash-screen allows you to kill the splash screen sooner if desired.)
In a standalone Common Graphics application that was generated from a project, this function is called automatically if the project's kill-splash-screen-when-ready option is true, as it is by default.
Generic Function, cg package
Arguments: project
Returns whether the standalone application that is generated from the specified project will close the application's splash screen as soon as the standalone application has finished starting up. The setf of this function could be used to programmatically set the value of this property, though typically you would set set it interactively with the Kill the Splash Screen When the App Is Ready check-box on the Build tab of the Project Manager dialog. The default value is t.
When this option is true, the user may begin using the app as soon as possible, rather than waiting until the splash screen goes away after an arbitrary amount of time. (See the descriptions of the +b, +Bt, and +Bp arguments in Command line arguments in startup.html. Those arguments control the initial display of a splash screen. +b and +Bt display the splash screen for three seconds, while +Bp displays it until the user clicks on it. kill-splash-screen-when-ready allows you to kill the splash screen sooner if desired.) If, on the other hand, the app comes up very quickly and you want the user to have more time to view the splash screen, then you may want to turn this option off.
When a standalone application that was generated from a project starts up, the function do-default-restart (which is normally the ide:on-restart function of a project) calls the project's ide:on-initialization function, and then calls kill-splash-screen if (kill-splash-screen-when-ready (app *system*)) returns true. (The project no longer exists in the standalone app, and so the value is cached on the "app" object.)
This option requires the cg.os-window Common Graphics module, which will be included automatically when needed by the Find Required CG Modules button on the Project Manager dialog's Include tab.
Generic Function, cg package
Arguments: outline-item
Returns the value of the kind slot of the argument. The kind property is not used internally, but an application can assign arbitrary values to this property in order to specialize methods of generic functions such as outline-item-closed-pixmap. For example, each outline-item that happens to represent a person could be given a "kind" property of :person, and then an outline-item-closed-pixmap method that uses an (eql :person) specializer for the kind argument would cause each of these outline-items to use a particular pixmap when in closed state.
kind is a property of the outline-item class.
Generic Function, cg package
Arguments: object
Returns a short string that is suitable for displaying to the user for the specified object, or nil when not applicable.
For a static-text widget, this maps to the value property. For other widgets, it maps to the title property. (Those other exported functions could be called instead of this one, but this one is handy for calling on any dialog-item.)
For a tab-info of a tab-control, a header-info of a header-control, or a header-cell of a grid-widget, this returns the string that is displayed in the object, and the setf of this function can be called to change the string that the object displays.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the height of the argument lamp. The value should be either nil or an integer. When nil, the value defaults to 10. When an integer, the lamp image will be that many pixels tall. The default value is nil.
See the description of the lamp control.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the shape the argument lamp. The value is a keyword symbol indicating the shape in which to draw the lamp image. The choices are :circle, :rectangle, :triangle, and :diamond. If the value property is an array (thus showing an array of lamps), then all of the lamp images will have this same shape. The default value is :circle, which is typically interpreted as an LED (light-emitting diode).
See the description of the lamp control.
Generic Function, cg package
Arguments: lamp-column-mixin
Returns the value of the lamp-widget property of a grid-column that uses the lamp-column-mixin class. The value may be set when creating the grid column by passing the lamp-widget initarg, or any time later by calling (setf lamp-widget).
The value should be a lamp widget. The widget would be created as usual for a dialog-item by calling make-instance, but typically you would not place the lamp widget onto a parent window like most widgets because it is being used by a grid column instead. Modifying the lamp widget will update the grid column as needed.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the width of the argument lamp. The value should be either nil or an integer. When nil, the value defaults to 10. When an integer, the lamp image will be that many pixels wide. The default value is nil.
See the description of the lamp control.
Generic Function, cg package
Arguments: list-view
An image-list instance that contains the pixmaps to display in this list-view when its layout-style is :large-icon. May also be nil (the default) to display no icons in the :large-icon layout style.
As with small-image-list, this property may alternately be specified as a list of names of cached pixmaps as a shortcut.
A large-image-list typically contains pixmaps that are 32 by 32 pixels in size. They can be other sizes, but may get clipped if larger due to the limited space that is reserved for the icons.
The icons will appear only if one or more of the list-view-items of the list-view have non-nil values for the icon-index property.
See the description of the list-view control.
Generic Function, cg package
Arguments: object-editor
Returns the height in pixels of the all-instances table of an object-editor dialog, if there is one. The value may be set at creation time with the layout-all-instances-table-height initarg, or any time later by calling (setf layout-all-instances-table-height). This value is used only when the all-instances table is created. See include-table-of-all-instances.
Generic Function, cg package
Arguments: layout-spacing
Returns the number of pixels between logical groups of the built-in command-buttons on an object-editor when it lays out its widgets. Settable with the layout-button-group-spacing initarg or by calling (setf layout-button-group-spacing). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the height in pixels of the built-in command-buttons of an object-editor when it lays out its widgets. Settable with the layout-button-height initarg or by calling (setf layout-button-height). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the number of pixels between buttons within a logical group of built-in command-buttons on an object-editor when it lays out its widgets. Settable with the layout-button-spacing initarg or by calling (setf layout-button-spacing). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the width in pixels of the built-in command-buttons of an object-editor when it lays out its widgets. Settable with the layout-button-width initarg or by calling (setf layout-button-width). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the number of pixels that will horizontally separate columns of widgets when they are laid out on an object-editor dialog. Settable with the layout-column-spacing initarg or by calling (setf layout-column-spacing). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the number of pixels that will horizontally separate each slot-editing widget from its label widget when they are laid out on an object-editor dialog. Settable with the layout-label-spacing initarg or by calling (setf layout-label-spacing). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the height in pixels of widgets that hold multiple lines of text, when they are laid out on an object-editor dialog. Settable with the layout-multi-line-widget-height initarg or by calling (setf layout-multi-line-widget-height). See layout-spacing.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the layout-orientation property of a chart-legend. The value may be set at creation time by passing the layout-orientation initarg, or any time later by calling (setf layout-orientation).
A value indicating how the multiple objects are arranged in the chart-legend of a chart-widget. Each object in the sequence of chart-objects of the chart-widget will have an entry in the legend (when the legend is included). Here are the possible values:
:columns - The first objects are arranged from top to bottom in a leftmost column of objects, then in a second column, and so on. The number of objects per column is chosen so as to minimize the number of rows, to use as little space as is feasible. If all objects fit into a single row, then each "column" will contain only a single object, and so this would be the same as :rows. This is the default value.
:rows - The first objects are arranged from left to right in a topmost row, then in a second row, and so on.
:one-column - All objects are arranged in a single column from top to bottom, even if multiple objects would fit in one row.
This property is used only when the draw-legend property of the chart-widget is true.
See also icon-size, icon-spacing, icon-line-length, horizontal-spacing, interior-horizontal-margin, and interior-vertical-margin.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: layout-spacing
Returns the size in pixels of the margin that will be left between the interior of the frame of an object-editor dialog and all widgets within it, when the object-editor lays out its widgets. Settable with the layout-outer-margin initarg or by calling (setf layout-outer-margin). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the height in pixels of widgets that hold a single line of text, when they are laid out on an object-editor dialog. Settable with the layout-single-line-widget-height initarg or by calling (setf layout-single-line-widget-height). See layout-spacing.
This particular property may be nil rather than a number, which will default the height of a widget to a size that's suitable for the widget's font. The default is nil.
Generic Function, cg package
Arguments: object-editor
Returns the layout-spacing object of an object-editor dialog. The value may be set at creation time with the layout-spacing initarg, or any time later by calling (setf layout-spacing). Typically a custom layout-spacing (if used) should be provided when the object-editor is created so that it is used for the initial widget layout.
Code for creating an object-editor with a layout-spacing could look something like this code fragment:
(make-window :my-object-editor
:class 'object-editor
:edited-class ...
:edited-slots ...
:layout-spacing (make-instance 'layout-spacing
:layout-widget-spacing 4
:layout-outer-margin 12
...))The value should be a layout-spacing object that was created by calling make-instance on the layout-spacing class. If a new object-editor is not explicitly given a layout-spacing object at creation time, then a layout-spacing object with default values is created automatically and given to the object-editor.
Generic Function, cg package
Arguments: list-view
This list-view option is supported only on the Windows platform.
Returns the layout-style of the argument. The value can be one of the four symbols :report, :list, :small-icon, or :large-icon. The value indicates the style in which the list-view control is to be drawn. These are the familiar alternate layouts of the Windows File Explorer.
The default style is :report, which is the only style that shows the column values that are stored in the value-plist property of each list-view-item. The :report style also includes headers for the columns.
The :list style is similar to :report in that it shows the list-view-items as a single vertical list, with the item's small icon beside the item's name, but it excludes the column values and column headers.
The :small-icon style is similar to the :list style in that it shows the small icon of each item beside the item's name, but the items are arranged in a rectangular array rather than in a list to make better use of the available space. The :large-icon style is similar to the :small-icon style except that it shows each item's large icon. In the :small-icon and :large-icon styles, the alignment property of the list-view determines how the icons are arranged into a rectangular array.
See the description of the list-view control.
Generic Function, cg package
Arguments: layout-spacing
Returns the height in pixels of any class-grid that is created when an object-editor lays out its widgets. Settable with the layout-table-height initarg or by calling (setf layout-table-height). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the number of pixels that will vertically separate widgets when they are laid out on an object-editor dialog. Settable with the layout-widget-spacing initarg or by calling (setf layout-widget-spacing). See layout-spacing.
Generic Function, cg package
Arguments: layout-spacing
Returns the default width in pixels of widgets when they are laid out on an object-editor dialog. Settable with the layout-widget-width initarg or by calling (setf layout-widget-width).
Some types of widgets have more specific defaults that override this one. A widget that holds a fixed number of characters will default to a width that is just large enough for that many characters. A pixmap widget will default to 32 pixels wide. See layout-spacing.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns the pixmap used to represent a leaf in the outline control specified by the argument.
leaf-pixmap is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns (or sets with setf) the symbol name of the pixmap instance used in outline to indicate an outline-item is a leaf. When setting this value, use a pixmap which has been placed in the set of cached pixmaps with cache-pixmap.
leaf-pixmap-name is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns (or sets with setf) the path namestring of the .bmp pixmap file from which the pixmap instance used in outline to indicate an outline-item is a leaf was originally read (if any). When this value is set, load-pixmap is called on the path namestring, a pixmap object is created, and the pixmap is cached with cache-pixmap.
leaf-pixmap-source is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: standard-object
Returns the value of the left property of standard-object. This property determines the position in pixels, using the left edge of parent as 0, of the object which is typically a control or window.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the left-attachment property of standard-object. This property determines how the distance between the object's left edge and the edge(s) of its parent window change when the parent gets resized.
The possible values and their effects are:
:right: object maintains a constant distance between its left edge and the right edge of its parent window whenever the parent is resized.
:left: object maintains a constant distance between its left edge and the left edge of its parent window whenever the parent is resized.
:scale: object maintains the same ratio of the distances from the left and right sides of its parent window whenever the parent is resized. I.e., if the left side was one-half of the way between the left and right edges of the parent before, then it is one-half of the way between the edges after resizing.
See also right-attachment, top-attachment, bottom-attachment, track-limits and resize-window.
Function, cg package
Arguments: text-edit-pane
Calls (setf justification) on text-edit-pane (a text-edit-pane) with the value :left. This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.
Generic Function, cg package
Arguments: graphical-stream &optional (stream-units-p t)
Returns the current left margin of a graphical-stream, measured from the left edge of the stream. The left-margin is initially zero, except as noted below. (setf left-margin) may be called to set the margin at any time.
If stream-units-p is true, as it is by default, then the margin is measured in pixels. If nil, it is measured in space character widths (see space-width).
Margin attributes are provided primarily to allow an application to keep a drawing within arbitrary margins by drawing everything within the coordinates returned by left-margin, top-margin, right-margin, and bottom-margin. Common Graphics also uses them in a few special ways, though, as described below.
Whenever a newline character is printed to a graphical-stream, the current-position-x of the stream is set to the stream's left-margin, and the current-position-y is incremented by the line-height of the stream. This causes the next line of text to be printed at the left margin and just below the previous line.
A text-edit-pane is an exception to the general newline behavior. It is a control that positions text in its own way, and inserting a newline does not add spaces or tabs to the text-editing area to reflect the stream's left margin. The left-margin of a text-edit-pane normally should be left at zero to allow pretty-printed output to fit the interior width of the window as usual (see right-margin). The function (setf text-edit-margins) may be called instead to establish or modify the margins for all of a text-edit-pane's text.
When opening a printer stream or calling new-page to advance to the next printed page, the current-position-x of the stream is set to its left-margin, and the current-position-y is set to its top-margin.
A printer stream's coordinate system has position (0, 0) at the printer-physical-offset of the printer. To allow an application to avoid dealing with this arbitrary offset, Common Graphics sets the margins of a printer stream to the distance from the physical offset to the margins selected by the user in the print job dialog or page setup dialog. This allows the application to maintain the requested paper margins by simply drawing everything within the four margins that were set up automatically. See *default-printer-left-margin* for more information.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the legend-font property of a chart-legend. The value may be set at creation time by passing the legend-font initarg, or any time later by calling (setf legend-font).
The font that is used to draw strings in the chart-legend of a chart-widget. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 12).
This property is used only when the draw-legend property of the chart-widget is true.
See also on-print-chart-object.
See chart-widget and also .
Generic Function, cg package
Arguments: line-drawing-view
Returns the value of the line-colors property of a line-drawing-view. The value may be set at creation time by passing the line-colors initarg, or any time later by calling (setf line-colors).
The colors that are used to draw the graph lines on a line-drawing-view in a chart-or-plot. The value should be a sequence (list or vector) of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list returned by the following (see make-rgb for a list of all pre-defined colors):
(list 'blue 'dark-green 'red 'dark-magenta 'dark-cyan
'gray 'black 'dark-yellow)If the value is nil, then all lines are drawn in black. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.
The line-colors are also used to draw the non-pixmap icon-images of the line-drawing-view when the icons-filled property is a value other than t. This property is otherwise used only when the draw-lines property is true.
See plot-widget, chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: stream
Returns, or sets with setf, the line dashing of stream. Values can be
:solid
:dot
:dash
:dash-dot
:double-dot
:long-dash
:dash-double-dot
stream should be a cg-stream.
Generic Function, cg package
Arguments: line-drawing-view
Returns the value of the line-dashings property of a line-drawing-view. The value may be set at creation time by passing the line-dashings initarg, or any time later by calling (setf line-dashings).
The dashing styles that are used to draw the graph lines on a line-drawing-view in a chart-or-plot. The value should be a list of values that are valid for the line-dashing property of a graphical-stream. The default value is a list of the symbol :solid.
If the value is nil, then all lines are drawn solid (non-dashed). Otherwise, the first object in the chart-or-plot's sequence of chart-objects is drawn with the first dashing style, the second object with the second style, and so on. If there are fewer dashing styles in the list than there are chart-objects, then the drawing code will cycle back through the list of styles as needed.
This property is used only when the draw-lines property is true.
See plot-widget, chart-widget and also .
Generic Function, cg package
Arguments: stream
Returns (or sets with setf) a symbol indicating the current style for drawing the ends of thick lines on stream. stream should be a cg-stream.
The possible values are
:round (the default): adds a round cap past the specified endpoint.
:square: adds a square cap (protruding by one-half of the width of the line).
:flat: ends the line immediately at the specified endpoint.
See also: with-line-end, line-join, with-line-join, begin-drawing-path, end-drawing-path, and with-drawing-path.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the line-graph-view property of a chart-widget. The value may be set at creation time by passing the :line-graph-view initarg, or any time later by calling (setf line-graph-view).
line-graph-view is the chart-view that draws a chart-widget's data as a line graph. The value is an instance of the line-graph-view class, and holds properties that are used whenever the chart-view property of the chart-widget is :line.
The value of this property is always a line-graph-view instance, even when this view is never used. If you do not pass a line-graph-view instance as the value of the :line-graph-view initarg when creating a chart-widget, then a default instance is created automatically.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: stream &key return-real
Returns the height of each line of text in stream.
stream should be a graphical-stream.
If return-real is true, then any non-integer real value is returned as is, and otherwise it is rounded to an integer. When running in a web browser, JavaScript returns real values, and return-real can be used to avoid roundoff errors (especially when multiplying the line height). This parameter was added in release 11.0.
The line height is the number of pixels taken up by a line of text, from the baseline of one line to the baseline of the next. When a newline is printed to the stream (as with draw-string-in-box or format), the current-position-y of the stream is incremented by this amount (and the current-position-x is set to the stream's left-margin).
The line height is set initially to the font-height of the initial font of the stream, and also when (setf font) or with-font is called on the stream. It may also be set directly if needed by calling (setf line-height).
Generic Function, cg package
Arguments: stream
Returns (or sets with setf) a symbol indicating the current style for drawing the vertices of thick polylines and polygons on stream. stream should be a cg-stream.
The possible values are:
:round (the default): rounds off each vertex.
:miter: extends each vertex to a single point (except where the angle is very small, which would extend the vertex unreasonably far).
:bevel: flattens each vertex.
See also: line-end, with-line-end, with-line-join, begin-drawing-path, end-drawing-path, and with-drawing-path.
Function, cg package
Arguments: stream &optional stream-units-p
Returns the value of the line-length attribute of stream. If stream-units-p is true the value is in stream units, otherwise it is in space-widths (the width of a space in the font of stream). This value is always an integer, rounded if necessary when stream-units-p is nil.
Generic Function, cg package
Arguments: stream character-index
Returns an integer indicating the line of text that contains the character whose index is character-index. The returned value 0 indicates the first line of text. character-index should be a non-negative integer (not a character object) indicating a number of characters from the beginning of the text. The value 0 indicates the first character. stream can be a multi-line-editable-text widget or a text-edit-pane.
If character-index is beyond the length of the text, then the returned value is still an integer even though there is no line index there. This integer is approximately the number-of-text-lines in the stream, but that number should not be counted on to be precise. (In one test case, it is one greater than the number of text lines in Windows desktop mode, but one less in web browser mode.)
See also char-from-line-number.
function, cg package
Arguments: line1-end1 line1-end2 line2-end1 line2-end2 &optional pos-to-return
Returns the point (a position object) at which two line segments intersect if they do intersect, and nil otherwise.
The first four arguments are position objects that specify the endpoints of the two line segments.
If pos-to-return is nil or unspecified, then a new position object is created and returned. Otherwise pos-to-return should be a position object, which will be modified and returned.
As usual, position objects should contain integers. See make-position.
See also line-segment-intersection-x-y.
function, cg package
Arguments: line1-end1-x line1-end1-y line1-end2-x line1-end2-y line2-end1-x line2-end1-y line2-end2-x line2-end2-y
Returns the point (x and y coordinates returned as multiple values) at which two line segments intersect if they do intersect, and returns nil otherwise.
The eight arguments are real numbers that specify the endpoints of the two line segments. See also line-segment-intersection which uses position objects rather than coordinates as arguments and return value.
function, cg package
Arguments: end1 end2 box
Returns whether a line segment intersects a box.
end1 and end2 are position objects (see make-position) that specify the endpoints of a line segment, and box is a box object (see make-box). If the objects intersect then true is returned, and otherwise nil is returned.
As usual, position and box objects should contain integers. See also line-segment-intersects-box-x-y-p.
function, cg package
Arguments: end1-x end1-y end2-x end2-y box-left box-top box-right box-bottom
Returns whether a line segment intersects a box.
The first four arguments are real numbers that specify the coordinates of the endpoints of the line segment. The remaining four arguments are real numbers that specify the sides of a box. If the objects intersect then true is returned, and otherwise nil is returned.
See also line-segment-intersects-box-p.
Generic Function, cg package
Arguments: stream
Returns the line texture of stream. stream should be a cg-stream.
Only :solid (draw in the foreground color) and :background (draw in the background color) are supported as line-textures. Only lines wider than 1 pixel are affected by line-texture.
Generic Function, cg package
Arguments: stream
Returns, or sets with setf, the line width of stream. The width is a fixnum number of pixels. 0 means draw the thinnest line possible. stream should be a cg-stream. The initial value is 1.
Generic Function, cg package
Arguments: line-drawing-view
Returns the value of the line-widths property of a line-drawing-view. The value may be set at creation time by passing the line-widths initarg, or any time later by calling (setf line-widths).
The line thicknesses (see line-width) that are used to draw the graph lines on a line-drawing-view in a chart-or-plot. The value should be a sequence (list or vector) of positive integers. The default value is a list of the number 2.
If the value is nil, then all lines are drawn with a width of 1. Otherwise, the first object in the chart-or-plot's sequence of chart-objects is drawn with the first line-width, the second object with the second width, and so on. If there are fewer line widths in the list than there are chart-objects, then the drawing code will cycle back through the list of widths as needed.
This property is used only when the draw-lines property is true.
See plot-widget, chart-widget and also .
function, cg package
Arguments: point1 point2 y
Returns the x coordinate where a line has a particular y coordinate, or nil for a horizontal line.
The first two arguments are position objects that specify any two distinct points on the line. The last argument is a real number for the y coordinate. The returned value is a real number or nil.
As usual, position objects should contain integers. See make-position. See also line-x-at-y-x-y and line-y-at-x.
function, cg package
Arguments: x1 y1 x2 y2 y
Returns the x coordinate where a line has a particular y coordinate, or nil for a horizontal line.
The first four arguments are real numbers that specify any two distinct points on the line. The last argument is a real number for the y coordinate. The returned value is a real number or nil.
See also line-x-at-y and line-y-at-x-x-y.
function, cg package
Arguments: point1 point2 x
Returns the y coordinate where a line has a particular x coordinate, or nil for a vertical line.
The first two arguments are position objects that specify any two distinct points on the line. The last argument is a real number for the x coordinate. The returned value is a real number or nil.
As usual, position objects should contain integers. See make-position. See also line-x-at-y and line-y-at-x-x-y.
function, cg package
Arguments: x1 y1 x2 y2 x
Returns the y coordinate where a line has a particular x coordinate, or nil for a vertical line.
The first four arguments are real numbers that specify any two distinct points on the line. The last argument is a real number for the x coordinate. The returned value is a real number or nil.
See also line-x-at-y-x-y and line-y-at-x.
Generic Function, cg package
Arguments: outline
Returns the lines-of-padding property of an outline widget. The value may be set at creation time by passing the lines-of-padding initarg to make-instance, or any time later by calling (setf lines-of-padding).
The value of this property should be a non-negative integer, and the default value is 4. When an outline-item is selected in the outline, the widget will automatically scroll vertically as needed so that at least that many items are scrolled into view both above and below the selected item. This provides context around the selected item, especially when the selected item is related in some way to neighboring items.
Function, cg package
Arguments: index links
Returns the link at a certain character index, if any. The links argument should be a list as returned by find-links. The returned link is a list of starting-index, ending-index and the link string.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: rich-edit-pane
Returns the link under the mouse cursor in rich-edit-pane (which must be an instance of the rich-edit-pane class), if any. find-links must have been called at some prior time to cache all of the links.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: rich-edit-pane position
Returns the link at a certain pixel position in the interior of rich-edit-pane (which must be an instance of the rich-edit-pane class), if any. The returned link is a list of starting-index, ending-index and the link string. find-links must have been called at some prior time to cache all of the links.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: rich-edit-pane
Returns the link at the current text cursor position in rich-edit-pane (which must be an instance of the rich-edit-pane class), if any. find-links must have been called at some prior time to cache all of the links.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: rich-edit-pane
Returns (or sets with setf) the color that will be used by default when find-links is called to find all of the link strings in a rich-edit-pane or rich-edit dialog. The link color defaults to blue.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: rich-edit-pane
Returns the list of links that were found by find-links and cached as the value of this property of rich-edit-pane. This property is setf'able, but normally it should be set only by calling find-links.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: widget-window widget
This method is called when focus is cleared from a control (widget).
Generic Function, cg package
Arguments: widget-window widget
This method is called when focus is drawn to a control (widget).
Generic Function, cg package
Arguments: widget index value
This generic function is called whenever the mouse cursor moves over an item in an item-list or list-view widget. An application could add methods to be notified whenever this happens, such as to show a help message about the value under the mouse cursor. A similar function for outline widgets is outline-item-mouse-in.
widget is the item-list or list-view widget.
index is the zero-based index of the item.
item is the element in the widget's range at index. For an item-list this is the actual value that is displayed, while for a list-view it is a list-view-item object, whose name and value-plist properties are likely of interest.
The default method calls the on-list-item-mouse-in function of the widget if it has one. It may be simpler to use that function of individual widgets than to define a widget subclass for using this generic function.
Generic Function, cg package
Arguments: list-view-column
Returns the list-view control containing the argument list-view-column.
Generic Function, cg package
Arguments: list-view item column
Returns a box that indicates the region of list-view that is occupied by the "cell" where the list-view item crosses column. The box is in the stream coordinates of the list-view, and so the value is not affected by the current scroll-position of the widget. This function should be needed only for the most sophisticated uses of a list-view.
The following example would return the box where the second list-view-item crosses the second list-view-column, in a list-view widget that is the value of my-list-view.
(list-view-cell-box my-list-view
(second (range my-list-view))
(second (columns my-list-view)))Generic Function, cg package
Arguments: list-view item-name column-name
Returns the value of list-view where the list-view-item named item-name crosses the list-view-column named column-name. setf may be used with this function to change a single "cell" value of a list-view.
Function, cg package
Arguments: list-view-item &optional position
This function returns a position object indicating the distance of the upper-left corner of a list-view-item from the inner upper-left corner of its list-view control. If the position argument is non-nil, then it should be a position object which will be destructively modified and returned, in order to avoid consing a new position object to return.
(setf list-view-item-position) may be called to programmatically move a list-view-item. This is probably useful only when the layout-style is either :small-icon or :large-icon. Note that (setf list-view-item-position) does not have the optional position argument. If the auto-arrange property of the list-view control has been turned on, then moving an item will result in all of the items immediately being arranged once again into a rectangular array, with the moved item being placed at the position closest to the arbitrary position to which it was moved.
See list-view.
Generic Function, cg package
Arguments: list-view column-name &optional reverse-p
Sorts the rows (list-view-items) of list-view by the values displayed in the column named column-name. If reverse-p is true, then the sort is done in reverse order. Note that while a list-view may be sorted by setting its sort-column property, or the sort order may be reversed by setting its sort-reverse property, only this function allows both to be specified simultaneously. Sorting with two steps (sorting the column and then reversing the sort) may cause a flash on the screen.
Function, cg package
Arguments: list-widget new-item &optional index
Adds new-item to the range for list-widget at index. An index of 0 indicates the top of the list. If index is nil (or unspecified), the new-item is added at the end of the list.
list-widget can be a single-item-list, a multi-item-list, or a combo-box.
Generic Function, cg package
Arguments: widget
Returns the index of the item in an item-list or list-view widget that currently has the keyboard focus. This is not necessarily the same item as the selected value, especially for a multi-item-list or when the multiple-selections property of a list-view is true.
The setf of this function can be called to move the focus to a different item without also changing the selected value. This is done internally when you type the first one or more characters of a list item in a multiple-selection widget, when you likely do not want to select the item. You can then press the spacebar to select the focused item if desired.
Function, cg package
Arguments: list-widget
Returns the index of the selected item in list-widget. Zero indicates the top item in the list. If no item is selected, nil is returned. If the widget is a multi-item-list, then a list of the selected values is returned, or nil if no items are selected.
list-widget can be a single-item-list, a multi-item-list, or a combo-box.
Function, cg package
Arguments: list-widget old-index new-index
Moves the item at old-index in list-widget so that it is positioned at new-index.
list-widget can be a single-item-list, a multi-item-list, or a combo-box.
Function, cg package
Arguments: list-widget index
Removes the item at index from list-widget.
list-widget can be a single-item-list, a multi-item-list, or a combo-box.
Function, cg package
Arguments: list-widget new-item index
Replaces the item at index in list-widget with new-item.
list-widget can be a single-item-list, a multi-item-list, or a combo-box.
Function, cg package
Arguments: list-widget index &optional off-p &key trigger-on-change
Changes the selection status of list-widget's item at the given index. If off-p is true the item will be deselected; otherwise it will be selected.
If trigger-on-change is true, then the value is changed by calling (setf value), which will call the widget's on-change function for a new value. If nil, then the value slot is set directly and the on-change function will never run. The default is nil for backward compatibility, though it is typically best to pass this argument as true.
The return value is undefined. (In releases prior to 8.1, when there was no trigger-on-change argument, this function returned true if the change was effective and nil if there was an error. The return value can no longer be interpreted to indicate success or failure.)
If list-widget is a multi-item-list and the index that is passed is -1, then all of the items are deselected if off-p is true and are selected if off-p is nil. off-p defaults to nil.
list-widget can be a single-item-list, a multi-item-list, or a combo-box.
Function, cg package
Arguments:
Loads all of the Common Graphics patches except "full-fasl" patches for whole Common Graphics modules.
You will not likely need to call this function because (1) the patches will be included in the IDE when you rebuild all images after downloading patches, (2) doing a (require :cg) in a base Lisp will call this function automatically at the end, and (3) generating a standalone application from a project in the IDE will build the Common Graphics patches into it.
In those cases this function is called after loading the fasl files for each CG module. That's important because loading a module's fasl file after loading patches would override any patches to functions that are in that module.
You may need to call this function in obscure situations such as if you load individual Common Graphics modules into a base Lisp, by using forms like (require :cg.base) and (require :cg.menu). That may also load patches to Common Graphics modules that are not present, but that should not cause a problem.
See also ide:load-ide-patches.
Generic Function, cg package
Arguments: text-edit-pane &optional pathname delay-redraw
Loads text from a text file into a multi-line text-editing window.
text-edit-pane should be the text-edit-pane to load the text into. Alternately it can be a text-edit-window, in which case the text will be loaded into the frame-child of the window. It may also be the window of a multi-line-editable-text widget.
pathname should be a pathname or path namestring of a text file, or else nil. If nil, the usual file-selection dialog is shown to let the user interactively select the file to load.
delay-redraw is used internally and is probably not useful in applications. It prevents the text-edit-pane from redrawing itself automatically to reveal the loaded text.
On the Windows platform, this function will attempt to determine if the file is in a 16-bit Unicode format (either little- or big-endian) or UTF8, and will read the text using that external format if so. Otherwise it will read the file using using the external format of the locale with which the Windows operating system is currently booted, on the assumption that it matches. The function external-format-for-save will return the format that load-file used, and calling save-file later on the text-edit-pane will write the file back in the same format (except for cases documented under external-format-for-saved-files and external-format-for-save).
See the configuration option load-utf8-if-no-bom which controls behavior when loading a text file with no byte order marker (BOM) bytes at the beginning.
Generic Function, cg package
Arguments: multi-line-editable-text
If this boolean property is true and drag-and-drop drops the pathname or path namestring of an existing file onto this multi-line-editable-text widget, then the contents of that file will be loaded into the widget (by calling load-file). If the dropped value is a list, then the first element of the list will be used as the potential file path (because dragging from an item-list always drags a list of the selected values, even when there is only one).
In all other cases, the text in the widget will be replaced by text for the dragged value itself (whereas paste-selection would instead insert the value into the existing text at the text cursor). As usual, a custom drop-put method could be added to override this built-in behavior.
Function, cg package
Arguments: filename
Loads a file that was earlier created with save-lisp-pixmap to recreate the pixmap that was saved therein, and returns the pixmap. Optionally, the source code file that was created by save-lisp-pixmap may be compiled, and then the resulting .fasl file passed to load-lisp-pixmap. load-lisp-pixmap just calls load to load the file. The only visible difference between this function and load is that this function returns the loaded pixmap. (load always returns t or nil.)
There may be no good reason to load a pixmap this way, since loading the pixmap from the original .bmp bitmap file (using load-pixmap) is probably at least as fast.
filename is a pathname or path namestring naming the file to be loaded.
Function, cg package
Arguments: pathname &key name pixmap-to-return (icon-index 0) make-unique-name use-gdi-plus
Loads a pixmap (pixel map) from a file and returns a pixmap object. The pixmap can then be drawn by calling copy-to-stream.
The file can be any of the various types of pixmap files that can be loaded by the underlying windowing system. On any platform these should include png, jpg, gif, bmp, and tiff files along with others. On Windows, icon files (.ico) can also be loaded.
The arguments are:
pathname: a pathname or path namestring naming the file from which to load the pixmap. An error is signaled if this file does not exist or if its contents are not in the standard format of one of the valid types of files.
When running in CG/JS mode, the value can alternately be the URL string of an image file on the Internet. It must be a complete URL, including the scheme such as https. This will work only when the machine that's running the app is connected to the Internet and the image page is available. The web browser will then fetch the image directly from the Internet, bypassing Lisp.
name: a symbol that will be used for the name of the pixmap. This symbol may be used in later calls to find-pixmap (if the pixmap is first cached by calling cache-pixmap), and appears in the print name of the pixmap. If nil, a unique symbol based on the name of the file from which the pixmap was loaded is created and used for the name.
pixmap-to-return: either nil or an existing pixmap object to re-use. If nil, a new pixmap object is created and returned. If a pixmap, the pixmap is "filled in" with the information read from the file and then returned. This argument may be useful for updating a pixmap object from an edited (or alternate) file while keeping the pixmap eq to the former version of it.
icon-index: a non-negative integer indicating which icon to read from a .ico icon file, where zero indicates the first icon. The default is zero. This argument applies only if pathname names a .ico icon file, and will be ignored otherwise.
make-unique-name: if true, ensures that the name for the pixmap (typically taken from the filename) is not already in use as the name of a cached pixmap.
use-gdi-plus: this argument is used only on the Windows platform, and only for bmp files. Through Allegro CL release 9.0, Common Graphics on Windows could load only bmp files. Common Graphics loaded a bmp file by parsing the file contents in Lisp. Now Common Graphics uses the newer GDI+ API of Windows, where Windows can load a variety of types of pixmap files itself. But for backward compatibility, if the file is a bmp file then by default the file will still be loaded "by hand" the old way. (We expect no difference in behavior, but are being cautious.) To use the new approach even if the file is a bmp file, pass use-gdi-plus as true.
See also save-pixmap (which creates pixmap files) and load-lisp-pixmap (which loads a Lisp file which will recreate a pixmap). cg-pixmaps.html discusses pixmaps in general.
Function, cg package
Arguments: pathname &key (icon-index 0)
Reads a pixmap from any device-independent bitmap file. These are typically .bmp files. You can also load .ico (icon) files. If you are loading a .ico file, the icon-index keyword argument specifies which icon to read from the file. The value of icon-index must be a non-negative integer, where zero indicates the first icon in the file. icon-index defaults to zero. icon-index is ignored if you are not loading a .ico file.
load-texture returns three values. The first two are the texture and a texture-info. The texture-info contains a colormap read from the pixmap file and is therefore appropriate for passing along with the pixel-map to the function copy-pixels-to-stream in order to draw the pixel-map on a window in its original colors. The third returned value is nil when a .bmp file is loaded. When a .ico file is loaded, the third returned value is a bitmap mask that defines the transparent areas of the image. This mask bitmap can be passed along with the main pixmap to copy-pixels-with-mask-to-stream.
The function load-texture-info reads and returns the texture-info of the file without returning the pixmap. It allows you to get the texture-info quickly, if that is all you want.
Function, cg package
Arguments: filename &optional index
Reads the bitmap file filename (usually a .bmp file but can be an .ico or even a .dll file) and returns the texture-info structure that reflects the size, bits-per-pixel, and colormap of the pixmap in the file. When reading from a .dll file that contains multiple bitmaps, index can be passed to specify the bitmap of interest in the file. The texture-info returned is the same as the second value returned by load-texture, but this function is much faster if all you want is the texture-info.
Generic Function, cg package
Arguments: cg-configuration
This option has an effect only when running in Windows desktop mode. In CG/JS mode, CG always saves and loads files in UTF8 format.
This CG configuration option determines whether the function load-file will assume that the file is in UTF8 format if it contains no byte order marker (BOM) bytes at the beginning. This affects the IDE's source code editor as well as calling load-file on a text-edit-pane in a CG application.
When true, load-file will read a file that has no BOM using the :utf8 external-format, and otherwise it will read it using the :default external-format, which is the external-format of the locale into which Windows is currently booted. On an English version of Windows, for example, the default external-format will typically be a Latin1 encoding.
If the external-format that is used does not match the format of the file that's being read, then the file will probably not be read correctly if it contains non-ASCII characters. If a file to be read has no BOM and is in neither UTF8 format nor the default format, then an application could use Common Lisp functions to load the file into a string (specifying the necessary external-format), and then call set-text to put the text into a text-edit-pane.
This option is nil by default, mostly for compatibility with existing files that have been written in the default format. Prior to Allegro CL 9.0, save-file and the IDE's source code editor always used the default format on Windows.
This option can be found on the Editor tab of the IDE's Options dialog.
See also external-format-for-saved-files and ide:compile-files-as-utf8.
Function, cg package
Arguments: object
Returns as a string the print name of object as if from the following format form (which downcases all capitals in the string):
(format nil "~(~A~)" object)If this function is made the value of the on-print event handler for a list widget, it will make symbol names more readable. The list widgets are single-item-list, multi-item-list, and combo-box).
Generic Function, cg package
Arguments: app
The expression (main-window-maker (app *system*)) returns the maker-function that was automatically generated for the main form of a project. This works only in a standalone application that was generated from a project, or within a Run | Run Project process in the IDE (otherwise nil is returned).
This function is called by default-init-function, which is the default ide:on-initialization function of a project, so that it can create the main window of any project. A custom ide:on-initialization function would typically call the ide:maker-function directly instead, but it might be useful to call main-window-maker to make an ide:on-initialization function more general.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-grid-line-color property of a chart-axis. The value may be set at creation time by passing the :major-grid-line-color initarg, or any time later by calling (setf major-grid-line-color).
The color that is used to draw major grid lines for a chart-axis across the body of its chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of light-gray.
This property is used only when the draw-major-grid-lines property of the chart-axis is true and the major-grid-line-width property is positive.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-grid-line-dashing property of a chart-axis. The value may be set at creation time by passing the :major-grid-line-dashing initarg, or any time later by calling (setf major-grid-line-dashing).
The dashing style that is used to draw major grid lines for a chart-axis across the body of its chart-widget. The valid values are the same as for the line-dashing property of a graphical-stream. The default value is :solid, which draws a "regular" non-dashed line.
This property is used only when the draw-major-grid-lines property of the chart-axis is true and the major-grid-line-width property is positive.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-grid-line-width property of a chart-axis. The value may be set at creation time by passing the :major-grid-line-width initarg, or any time later by calling (setf major-grid-line-width).
The line-width that is used to draw major grid lines for a chart-axis across the body of its chart-widget. The value should be a non-negative integer, and is measured in pixels. The default value is 1.
Major grid lines are drawn only when this property is positive and the draw-major-grid-lines property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
This property has an effect only on the Windows platform.
This property of a chart-axis indicates the angle at which labels will be drawn on the major tic marks of a chart-axis. This has an effect only when the axis is horizontal; tic labels on a vertical axis are always drawn horizontally.
The value may be set by passing the :major-label-angle initarg to make-instance, or any time later by calling (setf major-label-angle).
The value is measured in degrees counterclockwise, relative to the horizontal, and should be an integer between -90 and 90 inclusive. The default value is 0 to draw ordinary horizontal text.
When the value is negative, the string will angle downward, with its left end below the tic mark. When it is positive, it will angle upward with its right end below the tic mark. When zero, it will be centered about the tic mark. When nonzero, a tic label will not wrap to multiple lines of text when specified by major-label-wrapping. When -90 or 90, the label will be vertical, which draws a cleaner string than at an arbitrary angle.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-label-color property of a chart-axis. The value may be set at creation time by passing the :major-label-color initarg, or any time later by calling (setf major-label-color).
The color that is used to draw the label for each major tic position of a chart-axis in a chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of black.
This property is used only when the draw-major-labels property of the chart-axis is true.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-label-font property of a chart-axis. The value may be set at creation time by passing the :major-label-font initarg, or any time later by calling (setf major-label-font).
The font that is used to draw the label for each major tic position of a chart-axis in a chart-widget. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 12).
This property is used only when the draw-major-labels property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-label-frequency property of a chart-axis. The value may be set at creation time by passing the :major-label-frequency initarg, or any time later by calling (setf major-label-frequency).
The number of major tic positions between successive major tic labels. The value should be a positive integer. The default value is 1, which means that a label is drawn at every major tic position (when major tic labels are drawn at all). A value of 2 would draw a label only at every other major tic position, while 3 would draw a label at every third major tic position, and so on.
This property is used only when the draw-major-labels property of the chart-axis is true.
See also major-label-frequency-offset and minor-label-frequency.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-label-frequency-offset property of a chart-axis. The value may be set at creation time by passing the :major-label-frequency-offset initarg, or any time later by calling (setf major-label-frequency-offset).
The number of major tic positions before the first major tic label is drawn. The value should be a non-negative integer. The default value is 0, to draw the first major tic label at the first major tic position.
This property is meaningful only when the major-label-frequency is greater than one. If that property is 4, for example, and major-label-frequency-offset is 1, then major tic labels would be drawn at major tic positions 1, 5, 9 and so on.
If the chart-items-limit property of the chart-widget has caused some items to be pushed off, then this offset is relative to all current items plus the ones that have been pushed off, so that labels remain on the same logical chart items as some are pushed off.
This property is used only when the draw-major-labels property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: item-axis
Returns the value of the major-label-min-spacing property of a item-axis. The value may be set at creation time by passing the major-label-min-spacing initarg, or any time later by calling (setf major-label-min-spacing).
The minimum distance, measured in pixels, that is maintained between the labels at major tic positions of an item-axis in a chart-widget. The value should be a non-negative integer, or else nil for no minimum. The default value is 8.
When the value is a number, the distance between major tic positions will be large enough that there is at least that much space between successive major tic labels.
See also draw-major-labels.
See chart-widget and also .
Generic Function, cg package
Arguments: item-axis
Returns the value of the major-label-wrapping property of a item-axis. The value may be set at creation time by passing the major-label-wrapping initarg, or any time later by calling (setf major-label-wrapping).
A boolean value indicating whether labels at major tic positions of an item-axis in a chart-widget will wrap at spaces. The default value is t. Wrapping will be done only if the major-label-angle property is zero.
If true, then each major tic label will wrap to a new line of text at every space in the label string. The widget will automatically leave enough room to display the label that requires the most lines of text.
An alternative is to set this property to nil and then embed newline characters in the strings returned by the on-print-major-label function of the chart-axis.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: value-axis
Returns the value of the major-tic-increment property of a value-axis. The value may be set at creation time by passing the major-tic-increment initarg, or any time later by calling (setf major-tic-increment).
The value increment between successive major tic positions of a value-axis in a chart-widget. The value should be a positive real number, or else nil for the value to be computed automatically. The default value is nil.
When the value is computed automatically, this is done after the range-bottom and range-top of the value-axis have been determined. Then a major-tic-increment is chosen such that there are a few major increments between the range-bottom and range-top, at relatively "round" values.
As an example of specifying this property explicitly, let's say that you have data values that range from 307 to 384. If you set the range-bottom property to 300 and range-top to 400, then setting major-tic-increment to 20 would produce major tic positions at 300, 320, 340, 360, 380, and 400. Setting minor-tics-per-major-tic to 4 would then produce minor tic positions at 300, 305, 310, 315, 320, and so on.
To make the values increase in the atypical direction, use invert-axis rather than a negative major-tic-increment.
See chart-widget and also .
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-tic-length property of a chart-axis. The value may be set at creation time by passing the :major-tic-length initarg, or any time later by calling (setf major-tic-length).
The length, measured in pixels, of major tic marks on a chart-axis in a chart-widget. The value should be a non-negative integer. The default value is 6.
Major tic marks are drawn only when this property and major-tic-width are positive numbers and the draw-major-tics property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the major-tic-width property of a chart-axis. The value may be set at creation time by passing the :major-tic-width initarg, or any time later by calling (setf major-tic-width).
The thickness, measured in pixels, of major tic marks on a chart-axis in a chart-widget. The value should be a non-negative integer. The default value is 3.
Major tic marks are drawn only when this property and major-tic-length are positive numbers and the draw-major-tics property of the chart-axis is true.
See chart-widget and also .
Function, cg package
Arguments: left top right bottom
Makes and returns a box which has its top left corner at position (left, top) and its bottom right corner at position (right, bottom).
See also the description of the class box and other box constructors like nmake-box, make-box-from-corners, make-box-relative, and make-box-relative-from-corner.
See also the various readers box-top, box-left, box-bottom, and box-right. All are setf'able.
Function, cg package
Arguments: top-left bottom-right
Makes and returns a box which has its top left corner at position top-left and its bottom right corner at position bottom-right. Top-left and bottom-right must be position objects.
See also the description of the class box and other box constructors like make-box, make-box-relative, and make-box-relative-from-corner.
Function, cg package
Arguments: left top width height
Makes and returns a box of width width and height height which has its top left corner at the position defined by left and top. Equivalent to
(make-box left top (+ left width) (+ top height))See also the description of the class box and other box constructors like make-box, make-box-from-corners, and make-box-relative-from-corner.
Function, cg package
Arguments: top-left width height
Makes and returns a box of width width and height height which has its top left corner at the position top-left.
See also the description of the class box and other box constructors like make-box, make-box-from-corners, and make-box-relative.
Function, cg package
Arguments: family face size &optional style angle
Both make-font and make-font-ex return a font object with the given components. Family and face specify the family and face of the font. The two functions differ only in the interpretation of the size of a font. See below under the heading Font sizes for information on size and on the size-is-cell-height-p argument to make-font-ex.
Other than size, fonts are canonicalized so that those with the same components are eq.
The family argument is a general specification for the style of the font, and is used only if the requested face is not installed in the operating system, and only when running in Windows desktop mode. It may be one of these symbols:
:swiss: variable-width fonts without serifs
:roman: variable-width fonts with serifs
:modern: fixed-width fonts, with or without serifs
:script: fonts designed to look like cursive handwriting
:decorative: novelty fonts, such as Old English
or else nil if there is no preference.
The face argument specifies the unique name of an individual typeface that may be installed in the operating system. The name may be a string or symbol, though a string is now preferred and the symbol option is provided mainly for backward compatibility. The string is not case sensitive. If the requested face is not installed, then a default face for the requested family is used.
A list of all currently installed font face names is returned by the form (see font-faces, screen, and *system*):
(font-faces (screen *system*))If the exact font that was requested is not available, then either CG or the underlying windowing system will substitute an approximate font. Once the returned font has been assigned to a stream by calling (setf font), exact-font may be called on the font to return a font object whose family, face, size, and other attributes reflect the actual font being used.
The size should be a positive real number that indicates the height of the font in pixels. On Windows the value is typically an integer, though non-integer real numbers work as well.
The style may be either a list of any of the style keywords shown below, or a single number derived by adding the associated weights, or nil to indicate none of the optional styles. The keywords and their integer equivalents are:
:bold style has weight 1.
:italic style has weight 2.
:underline style has weight 4.
:condensed style has weight 32.
The angle argument specifies the angle at which to draw all strings that are drawn in this font. If nil or unspecified, then text is drawn at the usual horizontal angle. Otherwise angle should be an integer indicating degrees counterclockwise to rotate text from the usual horizontal angle. (So 90 for vertical, first letter lowest, 180 for upside down, and 270 for vertical, first letter highest. These are examples; angles which are not multiples of 90 are also supported.) The text will be rotated about the upper-left corner of the string. draw-string-in-box is therefore not suitable for drawing text at non-zero angles, and Common Lisp stream output functions such as format and princ should be used instead; these functions which will draw from the current-position of the stream at the angle of the font. font-angle applied to a font returns the angle.
See also ask-user-for-font and vary-font.
You may notice that the size specified to a Common Font dialog is different from the size specified to make-font to get the same result. For example, if you call ask-user-for-font (which displays a Common Font dialog), and ask for Times regular, size 11, you get the same font as returned by (make-font :roman :times 17).
Why the difference? There are two causes: first, Allegro CL measures font sizes in pixels while the Common Dialog measures in points; (see pixels-to-points and points-to-pixels); and second, the size shown in the Common Dialog indicates the "character height" (the height of the pixels that are actually drawn for a character) while the size used by make-font indicated the "cell height" (the character height plus an unpredictable number of blank pixel rows of "leading").
The function make-font-ex harmonizes Allegro CL with the Windows Common Font dialog. It uses character height rather than cell height (unless the size-is-cell-height-p optional argument is specified true, which forces the older cell-height interpretation and makes make-font-ex equivalent to make-font). The units are still pixels, though, rather than points.
Font objects are printed #.([make-font-form]) or #.([make-font-ex-form]). Every font created by make-font prints as #.([make-font-form]).
Fonts made by make-font-ex print as #.([make-font-ex-form]) or #.([make-font-form]) depending on which definition of size is used (controlled by the size-is-cell-height-p optional argument).
A font returned by a Common Font dialog prints as a make-font-ex form. Fonts made or created from other existing fonts will use the format of the starting font.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: family face size &optional style size-is-cell-height-p angle
Both make-font and make-font-ex return a font object with the given components. family and face specify the family and face of the font. The two functions differ only in the interpretation of the size of a font. See below under the heading Font sizes for information on size and the size-is-cell-height-p argument to make-font-ex.
Other than size, fonts are canonicalized so that those with the same components are eq.
The family argument is a general specification for the style of the font, and is used only if the requested face is not installed in the operating system, and only when running in Windows desktop mode. It may be one of these symbols:
:swiss: variable-width fonts without serifs
:roman: variable-width fonts with serifs
:modern: fixed-width fonts, with or without serifs
:script: fonts designed to look like cursive handwriting
:decorative: novelty fonts, such as Old English
or else nil if there is no preference.
The face argument specifies the unique name of an individual typeface that may be installed in the operating system. The name may be a string or symbol, though a string is now preferred and the symbol option is provided mainly for backward compatibility. The string is not case sensitive. If the requested face is not installed, then a default face for the requested family is used.
A list of all currently installed font face names is returned by the form (see font-faces, screen, and *system*):
(font-faces (screen *system*))If the exact font that was requested is not available, then either CG or the underlying windowing system will substitute an approximate font. Once the returned font has been assigned to a stream by calling (setf font), exact-font may be called on the font to return a font object whose family, face, size, and other attributes reflect the actual font being used.
The size should be a positive real number that indicates the height of the font in pixels. On Windows the value is typically an integer, though non-integer real numbers work as well.
The style may be either a list of any of the style keywords shown below, or a single number derived by adding the associated weights, or nil to indicate none of the optional styles. The keywords and their integer equivalents are:
:bold style has weight 1.
:italic style has weight 2.
:underline style has weight 4.
:condensed style has weight 32.
The angle argument specifies the angle at which to draw all strings that are drawn in this font. If nil or unspecified, then text is drawn at the usual horizontal angle. Otherwise angle should be an integer indicating degrees counterclockwise to rotate text from the usual horizontal angle. (So 90 for vertical, first letter lowest, 180 for upside down, and 270 for vertical, first letter highest. These are examples; angles which are not multiples of 90 are also supported.) The text will be rotated about the upper-left corner of the string. draw-string-in-box is therefore not suitable for drawing text at non-zero angles, and Common Lisp stream output functions such as format and princ should be used instead; these functions which will draw from the current-position of the stream at the angle of the font. font-angle applied to a font returns the angle.
See also ask-user-for-font and vary-font.
You may notice that the size specified to a Common Font dialog is different from the size specified to make-font to get the same result. For example, if you call ask-user-for-font (which displays a Common Font dialog), and ask for Times regular, size 11, you get the same font as returned by (make-font :roman :times 17).
Why the difference? There are two causes: first, Allegro CL measures font sizes in pixels while the Common Dialog measures in points, (see pixels-to-points and points-to-pixels); and second, the size shown in the Common Dialog indicates the "character height" (the height of the pixels that are actually drawn for a character) while the size used by make-font indicated the "cell height" (the character height plus an unpredictable number of blank pixel rows of "leading").
The function make-font-ex harmonizes Allegro CL with the Windows Common Font dialog. It uses character height rather than cell height (unless the size-is-cell-height-p optional argument is specified true, which forces the older cell-height interpretation and makes make-font-ex equivalent to make-font). The units are still pixels, though, rather than points.
Font objects are printed #.([make-font-form]) or #.([make-font-ex-form]). Every font created by make-font prints as #.([make-font-form]).
Fonts made by make-font-ex print as #.([make-font-ex-form]) or #.([make-font-form]) depending on which definition of size is used (controlled by the size-is-cell-height-p optional argument).
A font returned by a Common Font dialog prints as a make-font-ex form. Fonts made or created from other existing fonts will use the format of the starting font.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: &key ascent descent leading external-leading internal-leading height fixed-width-p truetype-p vector-p device-p average-char-width max-char-width direction
Creates a fontmetrics object with the specified values for the various attributes. However, it is usual to use this function to create a fontmetrics object without specifying values for any arguments and then use that object in a call to smash-fontmetrics or nfontmetrics.
See also Text and Fonts in cg-drawing.html.
Function, cg package
Arguments: stream
Creates and returns a graphics-context object that is valid for use with stream. stream should be a cg-stream.
A graphics-context object is useful only for passing to copy-graphics-context multiple times as the value of the optional result-context argument, in order to avoid consing a graphics-context object on each call. The stream should be the same value as passed to copy-graphics-context.
Function, cg package
Arguments: &key hue lightness saturation
Returns an hls color object with the specified values for hue, lightness, and saturation. The values for hue, lightness, and saturation must be as follows:
hue: a single-float between 0.0 and 360.0 inclusive. This specifies the color. A hue of 0.0 denotes red, 120.0 denotes green, and 240.0 denotes blue, with other values specifying other color.
lightness: a single-float between 0.0 and 1.0 inclusive. This denotes the strengh of the requested hue, where 0.0 is always black and 1.0 is full strength.
saturation: a single-float between 0.0 and 1.0 inclusive. This denotes the level to which the color is not grayed out (or whited out, when lightness is high). 1.0 denotes the "pure" color of the requested hue and 0.0 denotes a gray-scale color that varies from black (when lightness is 0.0) through medium gray (when lightness is 0.5) to white (when lightness is 1.0).
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
RGB colors (created with make-rgb) have values for red, green, and blue which are integers between 0 and 255 inclusive. Therefore, only 256256256 = 16,777,216 different RGB colors can be specified. Because HLS colors are specified with floats, apparently many more HLS colors can be specified (they are not all actually different, of course). Therefore, if you convert a HLS color to an RGB color (with hls-to-rgb), and then convert back with rgb-to-hls, the resulting hue, lightness, and saturation will likely differ from the originals by small amounts. The difference will be greater the smaller saturation and lightness are. A saturation of 0.0, means a shade of gray (with the hue having no effect) so converting such a color to RGB and back is likely to result in a very different hue.
See also make-rgb and hls-to-rgb, and hls-p, hls-hue, hls-saturation, and hls-lightness.
Function, cg package
Arguments: pane position
Creates and returns a mark at position of pane (a text-edit-pane). The mark location will be updated if text is inserted or removed before it (so, say, if you make a mark at the beginning of the second paragraph, it will be there however long or short the first paragraph is made). Use mark-position to find the position when needed.
This is not the mark set and operated on by Edit menu commands such as Set Mark and Swap with Mark.
Function, cg package
Arguments: string-or-pixmap &key owner width height horizontal-margin vertical-margin background-color foreground-color border font
This function is typically called internally by a user call to the with-message-window macro. Refer to with-message-window for complete information and a description of all the arguments.
make-message-window is provided in case you would like to show and remove the message window at times other than just before and after a with-message-window body. Calling this function will create a message window in :shrunk
Function, cg package
Arguments: x y
Returns a position object with the specified values of x and y. Both arguments should be fixnums. Position objects are instances of the (misnamed) position class. See About the position class in cgide.html for information (and for why the class is misnamed).
See also nmake-position, position-x, position-y, position+, position-, position*, position=, get-position, and positionp.
Function, cg package
Arguments: &key red green blue alpha scratch-rgb
Returns an rgb color object with the specified values of red, green, blue, and alpha. All arguments should be integers between 0 and 255. The red, green, and blue components default to 0, while the alpha component defaults to 255.
The alpha component is used only on Windows. It can create translucent effects where the existing background partly "shows through" new content being drawn. See the variable *alpha-blending* for more information.
If the scratch-rgb argument is specified, it should be a rgb object (such as created by make-rgb) which will be modified to have the new red, green, blue, and alpha values. This avoids consing a new rgb object and is particularly useful when many colors are created, used temporarily, and discarded.
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. If you use HLS colors, you should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
See also make-hls, hls-to-rgb, rgb-to-hls, and rgb-blue, rgb-red, rgb-green, rgb-equal, rgb-p, and rgb.
And see cg-color-palettes.html.
A number of RGB objects are pre-defined as the values of the following symbols:
Function, cg package
Arguments: x y &optional initial-value
A texture-contents object is a list of lists specifying the values at pixels in the texture (the value of the upper left pixel is the value of the first element of the first list). The lists are rows. This returns such an object with size x rows and y columns (i.e. x lists of y elements), initialized to value if supplied.
Function, cg package
Arguments: &key width height bits-per-pixel x-device-units-per-m y-device-units-per-m colors invert-p
Makes a texture-info structure, which is used along with a texture to draw a pixmap using copy-pixels-to-stream and so on.
The texture-info functionality remains largely for backward compatibility, and it is now recommended that pixmap objects be used instead since they encapsulate the separate texture, texture-info, mask-texture, and pixmap-handle objects.
A texture-info is a structure with fields (corresponding to the arguments):
width: an integer number of pixels.
height: an integer number of pixels.
bits-per-pixel: either 1,4,8, or 24
x-device-units-per-m: an integer specifying the horizontal resolution. nil means match stream.
y-device-units-per-m: an integer specifying the vertical resolution. nil means match stream.
colors: either a palette, or vector of rgb colors (see make-rgb), :rgb for 24 bit or nil, which means use palette of target stream.
invert-p: a boolean; if true, inverted.
Generic Function, cg package
Arguments: name &rest arguments &key (class 'frame-window) (owner (development-main-window *system*)) child-p dialog-items pop-up form-p child-name behind state border exterior interior exterior-top-left width height centered double-buffered &allow-other-keys
Creates and returns a new window, or returns nil if the request to the Operating System to create a new window fails (see the information under the heading make-window returns nil if a window cannot be created near the bottom of this page).
When calling CG functions on this window later, the safest approach is to always do that in the creation-process of the window, which will be the process that called make-window. See post-funcall-in-cg-process for details.
When using the Integrated Development Environment, you can design windows to be used in your application using forms. A form is a class of window that is used to design windows of other classes. The Integrated Development Environment creates a function from a form you have designed which creates the designed window. Get a new form by clicking File | New Form. You are asked for the class of the window (the value of the :class argument) and that is the type of window that will be designed with the form.
The required name argument should be a symbol (we recommend using keywords) which does not name any other window. The name can be passed as an argument to find-window and other find- functions to get a programmatic handle on a window.
Here are some keyword arguments to make-window:
:class: default: frame-window. The class of the window being created. The standard choices besides frame-window are text-edit-window, bitmap-window, dialog, rich-edit-dialog, and non-refreshing-window. We recommend that you subclass these standard classes so your customizations will not affect existing windows. In earlier releases, this argument was named device and that name is still accepted. Do not, of course, specify both.
The accessor/setter of the class property is device, though it is uncommon to need to use that function programmatically (one typically sets this slot upon creation or using the class slot in an inspector window). (class-name (class-of object)) also serves as an accessor.
:owner: an existing window (or the screen) that will be the owner of the new window. The default owner is the value returned by (development-main-window *system*), which is the invisible IDE owner window when the IDE is present, and otherwise the screen. See development-main-window.
A window shrinks or closes whenever its owner window does. If the child-p argument is true, then the owner will also be the parent of the new window. A window moves along with its parent, and is clipped at the interior edge of the parent. In earlier releases, this argument was named parent and that name is still accepted. Do not, of course, specify both.
:child-p: default is t. A boolean value indicating whether the new window will be a child window. If non-nil and the owner is a window rather than the screen, then the new window will be a child window and the owner window will also be its parent. A child window moves along with its parent and is clipped at the parent's interior border. If nil or the owner is the screen, then the new window will float freely about on the screen, but will still shrink and close along with its owner (if the owner is a window). The parent of a non-child window is the screen.
:dialog-items (formerly :widgets): default: nil. The value should be a list of controls (also called widgets, whence the former argument name) to be placed on the window. While controls can be placed on any window, only windows of type dialog-mixin (that is, only windows whose class is a subclass of dialog-mixin) will have the special Windows dialog behavior. In such windows, pressing the TAB key moves the keyboard focus from one control to another and pressing Alt-[letter] will move the keyboard focus to the control that has the letter underlined as its access character. (For example, pressing Alt-A will move keyboard focus to the control whose access letter is an underlined A.)
Each widget in the list is created by calling make-instance on a subclass of dialog-item. See the list of all widget classes in cgide.html. Each widget instance can be used on only a single parent window.
The use of :widgets to name this argument is deprecated. :dialog-items should be used instead. :widgets is accepted and both should not be specified.
:pop-up: default: nil. See pop-up. This argument should be specified true if the window is intended to be modal. Note that the value of this property cannot be changed once the window has been created.
:form-p: this parameter is for internal use by the IDE, and should not be specified by applications.
:child-name: when instantiating a window class that has the frame-with-single-child mixin (such as non-refreshing-window or bitmap-window), the :child-name argument may be passed to make-window to provide a name for the child pane that is created automatically for the frame window. As with other object names that are used in Allegro CL for finding objects, the name should be a symbol.
In fact it is unlikely that this name will be needed programmatically, since the child-pane can be found by calling frame-child on the parent frame window, it is nevertheless often helpful for arbitrary objects to have names so that the they can be recognized more easily during debugging.
:behind: this argument determines whether the new window should be placed behind or in front of its siblings in the occlusion stack. The default is nil, which places the window in front or its siblings. A value of t places the window behind all of its siblings. If the value is another window that is already on the owner window, the new window is placed immediately behind the specified window.
:state: the initial state of the newly created window. Possible states are :normal (window has its normal size and is visible, this is the default); :shrunk (window is shrunken and not visible); :icon (window is shrunk to a visible icon); and :maximized (window is extended to its maximum size).
When creating a window, the window is placed into its initial visible state (as specified by the :state initarg) by a device-open :around method. This means that if an application adds device-open methods (including :after methods) for its window subclasses, for example to set up child windows on the window, the main window will be shown only after this setup is complete, to avoid distracting the user and to increase creation speed. (An alternate approach is simply to create the main window in :shrunk state, then do arbitrary setup, and then set the state of the main window to :normal.)
:border: the style of the border (or frame) of the window. This mostly determines the border thickness, and sometimes the color. See the border property for the possible values.
:exterior: a box (see make-box) in the coordinates of the parent that determines the initial position and size of the exterior boundary of the window. Note that if the new window is a non-child window, then the box should always be in screen coordinates, even if the window has an owner window.
:interior: an alternative to :exterior, in that the box specifies the boundary of the client (interior) area of the window, again in the coordinates of the parent. The frame of the window will protrude outward from this box as needed.
:exterior-top-left: another alternative for the initial position. A position in the coordinates of the parent that determines the initial position of the top-left corner of the window. Another alternative is to pass individual coordinates using the :left and or :top arguments. If the window position is not determined by any make-window arguments or the default-initargs of the window class, then the initial position is determined by the default-top-left generic function.
:width and :height: another alternative for the initial size. Integers specifying the exterior width and/or height of the window in pixels. If the width and/or height are not determined by any make-window arguments or default-initargs of the window class, then the initial size is determined by the default-width and/or default-height generic functions.
:centered: specifies whether to initially center the window over the interior of its parent or owner. If nil (the default), then no centering is done. If :on-parent, then the window will be centered over its parent. For any other true value, the window will be centered over its owner. If an exterior or interior argument is passed along with a true centered argument, then the exterior or interior box will determine the size of the window while the centering will determine its position. A true centered argument would override an exterior-top-left argument. See also center-window and the centered property.
:double-buffered: specifies whether the window uses a memory bitmap to reduce flashing when redrawing the window. This option is nil by default for backward compatibility and because it uses memory resources, but it is generally recommended to pass this initarg as true for any window on which an application draws. See double-buffered.
Other window properties that may be passed to make-window as keyword arguments include title-bar, title, resizable, page-width, page-height, scrollbars, retain-scrollbars, handle-scrolling-keys, menu, font, background-color, show-help-string-under-mouse, small-canvas-mode, left-attachment, top-attachment, right-attachment, bottom-attachment, minimize-button, maximize-button, close-button, and help-button.
make-window returns nil if the operating system fails to make the requested window. Such failure is typically due to one of the operating system's tables for all windows and menus becoming full. This situation should be rare, but if it does happen, your application should be modified to close any windows or menus that are no longer being used, in order to free up the corresponding operating system resources. Windows may be closed programmatically by calling close on them.
Generic Function, cg package
Arguments: cg-configuration
When this configuration option is true, any control-left-click will be handled as a right-click with no shift keys down. That is, a control-left-click will cause mouse-right-down to be called with a buttons argument that does not include any bits for shift keys.
This option is true by default only on Mac OS X, where traditionally there is only a single mouse button and applications conventionally handle a Control-click as they would a right-click on other platforms. A Common Graphics application on the Mac could alternately set this option to nil and handle Control-clicks itself directly in mouse-left-down methods. With the default setting, existing mouse-right-down methods will work automatically on a Mac with the Control-click gesture.
This option does not appear on the IDE's Options dialog, but could be modified interactively with Tools | Inspect System Data | CG Configuration Options. It can be set programmatically with a form such as this one:
(setf (map-control-left-click-to-right-click (configuration *system*))
nil)Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-above-footnote property of a chart-or-plot. The value may be set at creation time by passing the :margin-above-footnote initarg, or any time later by calling (setf margin-above-footnote).
The distance, measured in pixels, between the footnote (if any) of a chart-or-plot and the bottom of the chart body (with axis labels if any). The value should be a non-negative integer. The default value is 4.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-above-legend property of a chart-or-plot. The value may be set at creation time by passing the :margin-above-legend initarg, or any time later by calling (setf margin-above-legend).
margin-above-legend is the height, measured in pixels, of the blank space that is left between the chart-legend of a chart-or-plot and the chart contents above the legend. The value should be a non-negative integer. The default value is 6.
This property is used only when the draw-legend property of the chart-or-plot is true.
See chart-widget, plot-widget, and also cg-chart-widget.html.
Generic Function, cg package
Arguments: scrolling-static-text
Returns the number of pixels of blank space that is reserved within a scrolling-static-text widget on each side of the text. The value may be set at creation time with the margin-around-text initarg, or any time later by calling (setf margin-around-text).
The value should be a non-negative integer. This property is most useful when a border is drawn by the border-color and/or draw-focus properties, to leave space between the text and the border. The default is 4.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-below-subtitle property of a chart-or-plot. The value may be set at creation time by passing the :margin-below-subtitle initarg, or any time later by calling (setf margin-below-subtitle).
The distance, measured in pixels, between the subtitle (if any) of a chart-or-plot and the chart body. The value should be a non-negative integer. The default value is 4.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-below-title property of a chart-or-plot. The value may be set at creation time by passing the :margin-below-title initarg, or any time later by calling (setf margin-below-title).
The distance, measured in pixels, between the main title (if any) of a chart-or-plot and everything else. The value should be a non-negative integer. The default value is 4.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the margin-inside-axis-label property of a chart-axis. The value may be set at creation time by passing the :margin-inside-axis-label initarg, or any time later by calling (setf margin-inside-axis-label).
The distance, measured in pixels, between the main label and the tic mark labels of a chart-axis in a chart-widget. The value should be a non-negative integer. The default value is 4.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the margin-inside-major-labels property of a chart-axis. The value may be set at creation time by passing the :margin-inside-major-labels initarg, or any time later by calling (setf margin-inside-major-labels).
The distance, measured in pixels, between a major tic label and its tic mark on a chart-axis in a chart-widget. The value should be a non-negative integer. The default value is 2.
If major tic marks are not drawn, then this is the margin between the major tic labels and the axis stem.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the margin-inside-minor-labels property of a chart-axis. The value may be set at creation time by passing the :margin-inside-minor-labels initarg, or any time later by calling (setf margin-inside-minor-labels).
The distance, measured in pixels, between a minor tic label and its tic mark on a chart-axis in a chart-widget. The value should be a non-negative integer. The default value is 2.
If minor tic marks are not drawn, then this is the margin between the minor tic labels and the axis stem.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-outer-bottom property of a chart-or-plot. The value may be set at creation time by passing the :margin-outer-bottom initarg, or any time later by calling (setf margin-outer-bottom).
margin-outer-bottom is the distance, measured in pixels, between the outer bottom edge of a chart-or-plot and anything that is drawn in the widget. The value should be a non-negative integer. The default value is 8.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-outer-left property of a chart-or-plot. The value may be set at creation time by passing the :margin-outer-left initarg, or any time later by calling (setf margin-outer-left).
margin-outer-left is the distance, measured in pixels, between the outer left edge of a chart-or-plot and anything that is drawn in the widget. The value should be a non-negative integer. The default value is 6.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-outer-right property of a chart-or-plot. The value may be set at creation time by passing the :margin-outer-right initarg, or any time later by calling (setf margin-outer-right).
margin-outer-right is the distance, measured in pixels, between the outer right edge of a chart-or-plot and anything that is drawn in the widget. The value should be a non-negative integer. The default value is 6.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the margin-outer-top property of a chart-or-plot. The value may be set at creation time by passing the :margin-outer-top initarg, or any time later by calling (setf margin-outer-top).
margin-outer-top is the distance, measured in pixels, between the outer top edge of a chart-or-plot and anything that is drawn in the widget. The value should be a non-negative integer. The default value is 6.
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments: struct
Returns the position (a number, not a position object) of the mark supplied as the argument. Such marks are made with make-mark.
Generic Function, cg package
Arguments: chart-axis
Returns the marker-lines property of a chart-axis object, which is associated with a chart-widget or plot-widget control. The value may be set at creation time by passing the :marker-lines initarg to make-instance, or any time later by calling (setf marker-lines).
Marker lines are straight line segments or thicker bands that are drawn perpendicular to a chart axis. Each line or band is drawn outward from a specified value (for a line) or range of values (for a band) along the axis, to highlight an arbitrary set of values.
An example would be a chart of economic statistics, where the item-axis represents time and has bands extending from it to mark where recessions have occurred in the past.
There are no entries in the chart legend for marker-lines. Their meaning could be noted in the subtitle or footnote text of a chart.
The value of the property should be a list of lists, where each sublist is a property list that describes one line or band to draw perpendicular to the axis. Here are the valid keys for each property list, and the type of value to specify for each one:
:value: every sublist should have a :value entry that specifies the point along the axis at which to draw a line or band. The value should be a real number (either an integer or not).
:value-to: if there is a :value-to entry, then a band will be drawn between the :value value to the :value-to value. Otherwise a line will be drawn at the :value value. The value should be a real number (either an integer or not).
:color: this is the color in which to draw the line or band. The value should be an RGB object (see make-rgb) or a symbol whose value is an RGB. When unspecified, the color will default to red for lines and light-gray for bands.
:line-width: this is the thickness (measured in pixels) with which to draw the line, when no :value-to is specified for a band. The value should be a positive integer. When unspecified, it defaults to 1.
:line-dashing: this is the dashing style with which to draw the line, when no :value-to is specified for a band. The value should be one of the keyword symbols that are valid values for the line-dashing property of a stream, such as :solid or :dash. When unspecified, it defaults to :solid.
Here is a sample value of the marker-lines property of an axis that would draw two lines and two bands:
((:value 3.5 :color blue :line-width 5 :line-dashing :dot)
(:value 6)
(:value 7 :value-to 8.5)
(:value 10.4 :value-to 15 :color cyan))Generic Function, cg package
Arguments: pixmap-or-cursor
Returns the mask of pixmap-or-cursor. The mask is a bitmap that defines the transparent area of the pixmap or mouse cursor. The mask value should be a 1-bit-per-pixel texture with a 1 wherever the pixmap or mouse cursor should be transparent (destination is left alone) and a 0 wherever the pixmap or mouse cursor should be opaque (the pixel for that location is drawn). The mask of a pixmap (if any) is usually specified either by setting the mask-contents property or by calling generate-mask.
Generic Function, cg package
Arguments: pixmap
Returns a value that specifies which pixels of a pixmap are transparent (if any). The value may be set either by calling (setf mask-contents) or by passing the :mask-contents initarg to make-instance when creating the pixmap.
pixmap should be a pixmap object. See cg-pixmaps.html for an overview of pixmap functionality.
The value returned by mask-contents or passed to (setf mask-contents) is nil when the pixmap has no mask. Otherwise it is a list of lists, where each inner list represents a row of the pixmap and each member of an inner list represents a pixel in that row. Each row member should be 1 to make the pixmap transparent at that pixel, or 0 to make it opaque. In addition, each transparent pixel must have a 0 in the main texture of the pixmap.
The number of inner lists reflects the number of rows in the pixmap, and the number of members in each inner list (these should all be the same) reflect the number of columns. These sizes for the mask should match the sizes that were used to specify the main image via the contents or texture property.
The mask of a pixmap may alternately be specified either by passing a texture to (setf mask), or by calling generate-mask.
Here is how Common Graphics makes the :default-leaf-with-mask pixmap, which is used by leaf nodes of outline widgets.
(cache-pixmap
(make-instance 'pixmap
:name :default-leaf-with-mask
:contents
'(( 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)
( 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)
( 0 0 0 15 15 15 15 15 0 0 0 0 0 0 0 0)
( 0 0 0 15 15 15 15 15 0 15 0 0 0 0 0 0)
( 0 0 0 15 15 15 15 15 0 15 15 0 0 0 0 0)
( 0 0 0 15 15 15 15 15 0 15 15 15 0 0 0 0)
( 0 0 0 15 15 15 15 15 0 0 0 0 0 0 0 0)
( 0 0 0 15 15 15 15 15 15 15 15 15 15 0 0 0)
( 0 0 0 15 15 15 15 15 15 15 15 15 15 0 0 0)
( 0 0 0 15 15 15 15 15 15 15 15 15 15 0 0 0)
( 0 0 0 15 15 15 15 15 15 15 15 15 15 0 0 0)
( 0 0 0 15 15 15 15 15 15 15 15 15 15 0 0 0)
( 0 0 0 15 15 15 15 15 15 15 15 15 15 0 0 0)
( 0 0 0 15 15 15 15 15 15 15 15 15 15 0 0 0)
( 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)
( 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0))
:mask-contents
'((1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1)
(1 1 0 0 0 0 0 0 0 1 1 1 1 1 1 1)
(1 1 0 0 0 0 0 0 0 0 1 1 1 1 1 1)
(1 1 0 0 0 0 0 0 0 0 0 1 1 1 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 1 1 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 1 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1)
(1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1))))mask-contents is a property of the pixmap and texture classes.
Generic Function, cg package
Arguments: pixmap x y
Returns the value of the specified pixel of the mask texture of a pixmap by calling contents-ref on the mask texture. Returns nil if the pixmap has no mask texture. See contents-ref for more information.
The setf sets the value of the pixel and returns the new value. It also does nothing and returns nil if there is no mask texture.
Generic Function, cg package
Arguments: pixmap x y value
Sets the value of the specified pixel of the mask texture of a pixmap by calling contents-set on the mask texture, and returns the new value. Does nothing and returns nil if the pixmap has no mask texture. See contents-set for more information.
Note that mask-contents-ref is setf'able and it is recommended you use setf and mask-contents-ref rather than this function.
Generic Function, cg package
Arguments: pixmap
Returns the handle to the device-dependent bitmap for the mask texture of the argument pixmap, if it has been given one by calling open-pixmap-handle, and otherwise returns nil. This function is useful for determining whether the pixmap currently has such a handle, though the particular handle is not useful for Common Graphics code. This handle corresponds to the mask texture stored in the mask property of the pixmap; see pixmap-handle for the handle corresponding to the main texture.
Generic Function, cg package
Arguments: basic-pane
Returns true if its argument (a window of some sort) has an active maximize button and returns nil if it does not. A maximize button expands a window to its maximum size.
On Windows, if a help-button is also specified for a window, the maximize button will not appear regardless of the value returned by this function.
The value may be set either by passing a :maximize-button initarg to make-window or by calling (setf maximize-button) any time later. The inspector will also display a maximize-button property for forms and other windows.
On Windows, the minimize and maximize buttons are both drawn whenever either or both are enabled, though if one is disabled then it will be grayed out and inactive. Neither will appear when both are disabled.
Generic Function, cg package
Arguments: *device8 &key notify-p wait-p
Closes device.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously.
If :notify-p is specified true, mci-notify is called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device is a compound device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-device &key from to notify-p wait-p
Deletes all or part of the recorded sound in an mci-wave-audio device. When from and to are both nil, this deletes the entire recording, which allows mci-set-wave-options to again be called on the wave device before recording to it again.
When either from or to is non-nil, it should be an integer indicating a position in the recording. The value depends on the current time format of the device; see mci-device-set-time-format and tmsf-to-integer. Typically a value to pass here was obtained by calling mci-device-position when playback was paused at some position of interest. Specifying such positions for both from and to allows editing out a small (or large) section of an audio recording.
device is an mci-wave-audio instance. If wait-p is true, then this function does not return until the operation is complete; otherwise the function returns immediately and the operation is performed asynchronously. If notify-p is true, then mci-notify is called when the operation has completed.
See the sample recording session at mci-record for more information.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the average bytes per second processed by device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the bits per sample of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the block alignment of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device can eject its media. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device can freeze. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device can play. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device is capable of recording. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p clv-p cav-p
Returns true if device can reverse direction. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device can save. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device can stretch. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the number of channels of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the current track of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the disc size accepted by device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-device
Returns the error function of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key * otify-p wait-p clv-p cav-p*
Returns the standard fast play rate of a videodisc player in frames per second. If clv-p is true, then the returned value applies to CLV format videodiscs. If cav-p is true, then the returned value applies to CAV format videodiscs. CAV is the default if no videodisc is inserted.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-device
Returns the file associated with mci-device.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the format tag of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device has audio. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device has video. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the handle to the palette of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the handle to the window of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-device
Returns the id of device. If mci-device-id returns 0, this indicates that the device is closed. This will be the case if the device has never been opened with mci-open, if it has more recently been closed with mci-close, or if the most recent call to mci-open resulted in an error. Otherwise mci-device-id will return a positive integer that is unique for the particular mci-device class, and which is of no use to the application other than the fact that it is positive to indicate that the device is open.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the input of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the inputs of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the length of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the level of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the max number of windows of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if media is present in device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the media type of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the mode of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Function, cg package
Arguments: mci-device
Returns the name of device.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p clv-p cav-p
Returns the normal play rate of a videodisc player in frames per second. If clv-p is true, then the returned value applies to CLV format videodiscs. If cav-p is true, then the returned value applies to CAV format videodiscs. CAV is the default if no videodisc is inserted.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-device
Returns the number of device.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the number of tracks of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the output of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the outputs of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device has palettes. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the position of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device is ready. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the samples per second of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key (channel :all) notify-p wait-p
Sets the audio of device for the indicated channel to off.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify is called upon completion.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key (channel :all) notify-p wait-p
Sets the audio of device for the indicated channel to on.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify is called upon completion.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Closes the door of device.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify is called upon completion.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Opens the door of device.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify is called upon completion.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Sets the time format of device to format.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify is called upon completion.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Sets the video of device to off.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify is called upon completion.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Sets the video of device to on.
If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify is called upon completion.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the side of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p clv-p cav-p
Returns the standard slow play rate of a videodisc player in frames per second. If clv-p is true, then the returned value applies to CLV format videodiscs. If cav-p is true, then the returned value applies to CAV format videodiscs. CAV is the default if no videodisc is inserted.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the speed of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the start position of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device can stretch its media. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the time format of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device track &key notify-p wait-p
Returns the track length of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device track &key notify-p wait-p
Returns the track position of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns the type of device. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-device
Returns the type constant (a number) of device.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-device
Returns type string of device.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Returns true if device uses files and returns nil if it does not. The keyword arguments are ignored.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device status device-id
This is the default notification method. It will call the user's error-function if they have put a function name into the error-function slot of the device. Otherwise it prints a notification. The error-function should take the parameters shown here (device, status, and device-id).
The status is either :success, :superseded, :aborted, or :failure.
An alternate approach is to define this method for whole subclasses, and not pass in an error-function to individual instances.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &rest args &key notify-p wait-p shareable-p use-device-number-p device-number device-name alias file mci-parent-window nostatic-p window-style buffer-seconds
Opens device with state as indicated by the arguments. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Pauses device. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key from to notify-p wait-p fast-p slow-p reverse-p scan-p speed
Plays device. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key from to notify-p wait-p insert-p overwrite-p
Records audio that may be saved as a nil to default to recording at the end of the already-recorded audio on this device (if any), or else an integer indicating the starting position within the already-recorded audio (see mci-device-set-time-format and tmsf-to-integer) from which to begin overwritting. to may be either nil to default to recording indefinitely until mci-stop is called, or else a position indicating the position at which to stop recording automatically.
If the wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Here is a sample recording session as a series of top-level forms that may be evaluated sequentially in the IDE editor, for example. Note that mci-record returns immediately though recording continues until the mci-stop call is made. A real application would typically have widgets that make these calls.
When recording audio, a microphone or other audio input must be connected to a sound card, with a driver for that sound card selected as the default audio device in Control Panel. The sound card may have a mixer applet in which you must select the current recording input jack(s) and level.
(use-package :cg)
;; Create and open a wave audio device for recording.
(setq wav (make-instance 'mci-wave-audio))
(mci-open wav)
;; Check the default audio quality (low).
(mci-device-bits-per-sample wav) ;; ==> 8
(mci-device-samples-per-second wav) ;; ==> 11025
(mci-device-channels wav) ;; ==> 1 (monophonic)
;; Set higher quality audio before recording.
(mci-set-wave-options wav
:bits-per-sample 16
:samples-per-second 48000
:channels 1) ;; still monophonic for now
;; Try a recording.
(mci-record wav) ;; recording starts now (start talking ...)
(mci-stop wav) ;; recording stops now
(mci-record wav) ;; append more recording to the end
(mci-stop wav) ;; stop again
;; Save the recording so far to a .wav file.
(mci-save wav :file "c:\\temp1.wav")
;; Play back what we've recorded.
(mci-seek wav :seek-to-start-p t) ;; rewind to beginning
(mci-play wav) ;; play from current position
(mci-stop wav) ;; interrupt a long playback
;; Start over, re-using the same device.
(mci-delete wav) ;; delete everything recorded so far
(mci-set-wave-options wav ;; try a stereo recording this time
:bits-per-sample 16
:samples-per-second 48000
:channels 2) ;; stereo
(mci-record wav) ;; record from scratch
(mci-stop wav) ;; stop recording
;; Try "editing out" a middle section of the recording.
(mci-seek wav :seek-to-start-p t) ;; rewind to beginning
(mci-play wav) ;; play the recording for a little while
(mci-stop wav) ;; stop in the middle of playback
(setq from (mci-device-position wav)) ;; remember where we stopped
(mci-play wav) ;; play back a bit further
(mci-stop wav) ;; stop playback again
(setq to (mci-device-position wav)) ;; remember where we stopped again
(mci-delete wav :from from :to to) ;; delete the middle section
(mci-seek wav :seek-to-start-p t) ;; rewind to beginning
(mci-play wav) ;; play the edited recording
;; Save the edited recording over the file that was saved earlier.
(mci-save wav :file "c:\\temp1.wav")
(mci-close wav) ;; close the device when we're done with itGeneric Function, cg package
Arguments: device &key notify-p wait-p
Resumes device. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Saves the contents of device to file. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p seek-to-end-p seek-to-start-p reverse-p to
Causes device to seek. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Function, cg package
Arguments: command-string &key callback-window
Command-string should be a standard MCI command string, exactly the same as if it were passed from C or any other language using the winapi function mciSendString. Refer to the Microsoft MCI command string documentation to learn how to formulate particular strings.
If callback-window is passed (it should be a window) and the command string includes the word "notify", then when the operation has completed the mci-notify generic function will be called with the callback-window as its first argument. You may respond to these notifications by defining your own mci-notify method on your own window class, and then passing an instance of that class as the callback window to mci-send-string. The parameters of mci-notify are: ((window basic-pane) status device-id).
mci-send-string is an alternative to using various other mci functions such as mci-open and mci-play. Since each command is sent to the operating system as a literal string, mci-send-string may not be as efficient as the other mci functions, but its advantages are that (1) you can send the same standard mci strings that you would send from any other language using the winapi function mciSendString, and (2) you can presently send any MCI command this way, whereas Allegro has not yet implemented some MCI commands as individual functions.
The following example will open the "tada" wave file from the Windows
> (mci-send-string
"open waveaudio!c:\\windows\\media\\tada.wav
alias yay notify"
:callback-window (find-window :debug-window))
"1"The default mci-notify method was called on :debug-window with a :success notification for MCI device 1.
> (mci-send-string "play yay from 140 notify"
:callback-window (find-window :debug-window))
""The default mci-notify method was called on :debug-window with a :success notification for MCI device 1.
> (mci-send-string "close yay")
""See cg-mci.html for information about MCI support in Common Graphics.
Function, cg package
Arguments: device &key bits-per-sample samples-per-second channels notify-p wait-p
Sets the audio quality and other options for recording a wave file. This function is necessary for decent quality audio in MCI, since the default quality is rather low.
Each of the options bits-per-sample, samples-per-second, and channels may be either nil to not modify that attribute, or else an integer indicating a new value for that attribute. The values that have a desirable effect may depend on the sound card's driver, and it is not clear how to determine programmatically what values will work well.
bits-per-sample is the number of bits used to store each sample. The default is 8 (low quality). 16 is audio-CD quality and is recommended.
samples-per-second is the number of samples that are recorded for each second of sound. The default is 11025 (low quality). A common high-quality sampling resolution that has worked well in our brief tests on a basic sound card is 48000. Audio CDs use 44100, though in our tests on a basic sound card this value did not produce high-quality audio (perhaps the proper value is not exactly 44100). Some applications that burn audio CDs require that the wave file already be in 16-bit, 44.1k resolution format though.
channels (when non-nil) may be either 1 for a monophonic recording or 2 for a stereo recording.
If this function is called, it must be called before any recording is done on the device, or after mci-delete is called to erase everything that has been recorded on the device.
device is an mci-wave-audio instance. If wait-p is true, then this function does not return until the operation is complete; otherwise the function returns immediately and the operation is performed asynchronously. If notify-p is true, then mci-notify is called when the operation has completed.
See the sample recording session at mci-record for more information.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: mci-animation window
This generic function determines the window in which an mci-animation will play back .avi files. The mci-animation instance should already be open (see mci-open) when this function is called. Any subsequent playback of the animation (see mci-play) will show the animation in the specified window. If this function is not called before an animation is played, the animation will appear in a new non-Common Graphics window over which Common Graphics has no control, so it is probably best to always use this function to control where an mci-animation appears.
window should typically be an instance of the frame-window or non-refreshing-pane classes, or a subclass of one of these. Though any type of window will work, text-edit-panes and the windows of controls (such as dialogs) are intended for displaying specialized content and so are probably not suitable. A bitmap-pane would work, but its backing store is not able to redisplay the current frame of the animation and therefore has no advantage for an animation.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p (frames 1) reverse-p
Steps device by the indicated number of frames forward unless reverse-p is true. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key notify-p wait-p
Stops device. If the :wait-p argument is specified true, this function will not return until the action is completed. If nil, this function is run asynchronously. If notify-p is true, mci-notify will be called when this function completes.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: device &key quantity-p name-p open-only-p install-name-p
Returns a string or number containing descriptive information about the MCI device as requested by the keyword arguments. Exactly one of quantity-p, name-p, or install-name-p should be passed as true.
If quantity-p is true, then the number of devices of the same type as device is returned as an integer. If open-only-p is nil then this is the number of such devices that are listed in the registry; if open-only-p is true then this is the number of such devices that are currently open.
If name-p is true, then a device name or names are returned as a string. If open-only-p is true, then the names for all of the currently open devices are returned. If open-only-p is nil, then the device name for the type of device is returned.
If install-name-p is true, then the name of the type of device of mci-device (listed in the registry or the system.ini file) that was used to install the device is returned.
See cg-mci.html for information about MCI support in Common Graphics.
Generic Function, cg package
Arguments: media-player command-name
Starts or stops the playback of an audio-player or video-player widget. The command-name should be one of the keyword symbols :play or :pause.
Pausing playback will leave the current playback time where it paused, and playing will begin from the current playback time. The current playback time can be set arbitrarily with media-player-property.
Function, cg package
Arguments: widget property-name
Returns the current value of one of the properties of an audio-player or video-player widget. The property-name should be one of the keyword symbols in (:display-controls :volume :current-time :duration :paused :ended :muted :looping :autoplay :playback-rate).
The setf of this function can be called to modify most of the properties, namely any in (:display-controls :volume :current-time :muted :looping :autoplay :playback-rate). The others are not modifiable.
Only the :display-controls property can be specified at widget creation time, by passing a :display-controls initarg as true or nil, where the default value is true. The other properties can be set only with this function.
Here are the meanings of the various properties:
:display-controls - Whether the player displays interactive gadgets for playing and pausing and setting the current playback time and so on. Otherwise the audio-player is not seen at all. Some browsers may always display the controls for the video-player.
:volume - The current playback loudness, from 0.0 (silent) to 1.0 (loudest).
:current-time - The number of seconds from the beginning at which the file is currently playing or will begin playing.
:duration - The total length of the media in seconds.
:paused - True when the media is not currently playing.
:ended - True when the media has finished playing to the end.
:muted - True when the audio is silent.
:looping - True when the media will begin playing from the beginning when it reaches the end.
:autoplay - True when the media will begin playing automatically as soon as it is ready. This may be considered impolite.
:playback-rate - The speed at which the media is currently playing or will play. For example, 1.0 is normal speed, 0.5 is half speed, and 2.0 is double speed.
Generic Function, cg package
Arguments: frame-window
Returns the menu-bar of frame-window. The menu-bar is displayed along the top of the frame-window.
The setf of this function may be called to add a menu-bar to a window. The new value may be a menu-bar that was created by calling open-menu, or nil to remove the window's current menu-bar if there is one. A menu-bar should not exist on more than one window at the same time, though it may be removed from one window and then added to another.
A menu-bar is structured the same way as a pop-up menu, except that each of its menu-items denotes one of the pull-down menus of the menubar, with the title of the menu-item being a pull-down menu title that is displayed along the menu-bar, and the value of the menu-item being a menu containing the pull-down menu's items.
If you use the IDE, you can add a menubar to a form (and thus to the window associated to the form in the application) by clicking on the extended editor button of the menu property of the form. Doing so displays the Menu Editor.
Common Graphics does not automatically close a menu-bar when it is removed from a window, because in general menus may be reused on the same or other windows or parent menus, and so Common Graphics does not know whether you are done with a menu-bar when you remove it. Any menus that are not closed explicitly by an application are closed automatically when Lisp exits, and so there is ordinarily no need for an application to close its menus. But if so many menus are being created that the operating system runs out of related resources (leading to errors), the application may call close on each menu that will no longer be used. A menu-bar should be removed from its window before calling close on it. Closing a menu does not close its submenus, and so these must be closed individually (either before or after closing the parent menu) to close an entire menu hierarchy.
Menu-bar access keys and keyboard shortcuts will never be routed to a child window, and will go to the menu-bar of the top-level parent (or its owner window) instead, if it has a menu-bar.
The menu-bar is actually a child pane that emulates a "real" menu-bar, because MS Windows does not allow menu bars on child windows. This primarily means that other windows must be offset downward by (menu-bar-height) to avoid covering (or being covered by) the menu bar pane.
Exposing one pull-down menu and then moving the mouse over the title of another pull-down menu does not remove the first menu and expose the second one. This is probably not feasible to improve because Common Graphics is waiting on a foreign function call that pops up the menu and tracks it within the operating system. Instead you must click on the second menu's title to show that menu.
Function, cg package
Arguments:
Returns the standard height for any menu-bar on a window.
You likely will need to know this value if you create menu-bars on child windows. In the Windows operating system, child windows are not allowed to have menu-bars. Common Graphics now allows it anyway by implementing a menu-bar pane that emulates the one in the underlying window system. This menu bar (on a child window) is not part of the window's frame, though, and so it takes up space in the user coordinate system of the window. You will therefore need to position any widgets or windows that are in the child window that has a menu-bar so that they are below the menu-bar. See menu.
Generic Function, cg package
Arguments: object
Returns true if the argument is an instance of the menu-bar class; returns nil otherwise.
Function, cg package
Arguments:
Returns the font used in menus.
Generic Function, cg package
Arguments: owner-window-or-screen menu menu-item
This generic function is called whenever the user presses the F1 key while a pop-up-menu or pull-down-menu is displayed and one of the menu items is highlighted. An application can add menu-item-help methods to show help for the menu itself or for the currently highlighted menu-item on the menu.
owner-window-or-screen is the window that owns the menu (see the stream argument to open-menu). menu is the menu that is currently displayed. menu-item is the menu-item that is currently highlighted on the menu. (If no menu-item is highlighted, then menu-item-help is not called.)
The built-in Common Graphics methods do nothing, though the IDE's menu-bar implements a menu-item-help method to show HTML help on the entire pull-down menu being displayed (since there are not individual pages for each menu-item).
Generic Function, cg package
Arguments: window menu menu-item menu-bar-p
This generic function is called each time a menu-item is highlighted as the user moves the mouse over the items of any menu. Methods may be added to this generic function to customize how an application shows the help-strings of menu-items to the end user.
window is the parent window of the menu, menu is the menu that the menu-item is on, menu-item is the menu-item itself, and menu-bar-p is a boolean, true if the menu is part of a menu-bar menu hierarchy and nil otherwise.
The built-in methods display the help-string of the highlighted menu-item in the status bar of the window that the menu is on, if it has a status bar. For a pop-up-menu, this is the window that was passed as the stream argument to the function pop-up-menu, if any.
Below is a sample method that is similar to the built-in methods; a custom method could be modeled after this one. Note that this method would be called for pop-up menus only, since it specializes on menu-bar-p being nil.
(defmethod menu-item-highlighted ((window my-window-class)
(menu menu)
(menu-item menu-item)
(menu-bar-p (eql nil)))
(let* ((string (help-string menu-item)))
(when string
(window-message my-window "~a" string))))See also show-help-strings-as-tooltips, which provides for help strings being displayed as tooltips. See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: object
Returns true if object is an instance of the menu-item class; returns nil otherwise.
Generic Function, cg package
Arguments: menu
Returns the list of menu-items included in menu. This list must not be modified, particularly when calling update-menu. That function takes as an argument a list of menu items, and that list becomes the new list of menu-items for the menu. You must not take the list returned by this function and destructively modify it, because the returned list is used along with the new (argument) list by the system to update the menu.
Generic Function, cg package
Arguments: range-object-list row column
This generic function is called when a grid combo-box cell (a cell in a combo-box-column-mixin column) is about to show its choices to the user as a pop-up menu that is displayed somewhat like a combo-box. The method returns a list of menu-items to display. The menu-values are a list of the actual choices for the cell, as returned by the column's range-reader function called on the row's data-object.
The default method creates menu-items with the print-name of each choice displayed in the menu. An application could add a method to this generic function to instead create menu-items that have some sort of alternative string displayed on the menu for each choice.
Here's an example of defining a custom menu-items-for-combo-box-range method for an application's own combo-box grid-column subclass. The method adds a sequential number (1 through N) to each of the choices that are displayed to the user.
(defclass my-combo-box-column
(combo-box-column-mixin grid-column)())
(defmethod menu-items-for-combo-box-range
(range-object-list row (column my-combo-box-column))
(declare (ignore row))
(let* ((number 0))
(mapcar #'(lambda (object)
(make-instance 'menu-item
:value object
:title (format nil "~a ~a" (incf number) object)))
range-object-list)))Generic Function, cg package
Arguments: configuration
The value of this property is the number of milliseconds that the mouse must linger over one of the IDE menu-bar's menu-items before its tooltip will appear. This internally uses the built-in cg-timer. The initial value is 1400.
menu-tooltip-delay is a property of the configuration class. The current configuration is the value of (configuration *system*) (see configuration and *system*).
See also show-help-strings-as-tooltips. and see cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: x
Returns true if the argument is an instance of the menu class; otherwise returns nil.
Function, cg package
Arguments: message title &key topmost
Displays, using the platforms's low-level utility, a simple message dialog, with title title and message message. If topmost is specified true, the message window will be a topmost window (staying above all other windows whether related to Lisp or not). This function returns what the low-level utility returns, which is typically not meaningful.
Function, cg package
Arguments:
The font used in common status bars.
Generic Function, cg package
Arguments: split-bar
Returns the min-space-after property of a split-bar widget. The value may be set at creation time by passing the :min-space-after initarg to make-instance, or any time later by call (setf min-space-after).
This is the minimum space to maintain either below a horizontal split-bar or to the right of of a vertical split-bar. The value is measured in pixels, and refers to the distance between the split-bar and either another split-bar or the interior edge of the parent window.
The user will not be able to interactively drag the split-bar to where the distance would be less than this minimum. This is to ensure that enough space is left to display the contents of widgets that are moved or resized by the split-bar (see widgets-to-move and widgets-to-resize).
The value should be a non-negative integer. The default value is zero, which allows the user to drag the split-bar so that it butts against the nearest other split-bar or the edge of the window, but not to overlap it. The value may be set at creation time by passing the :min-space-after initarg to make-instance, or any time later by call (setf min-space-after).
If this property, along with min-space-before, is not adequate for constraining the dragging of a split-bar, then an on-drag function could be supplied.
Generic Function, cg package
Arguments: split-bar
Returns the min-space-before property of a split-bar widget. The value may be set at creation time by passing the :min-space-before initarg to make-instance, or any time later by call (setf min-space-before).
This is the minimum space to maintain either above a horizontal split-bar or to the left of of a vertical split-bar. The value is measured in pixels, and refers to the distance between the split-bar and either another split-bar or the interior edge of the parent window.
The user will not be able to interactively drag the split-bar to where the distance would be less than this minimum. This is to ensure that enough space is left to display the contents of widgets that are moved or resized by the split-bar (see widgets-to-move and widgets-to-resize).
The value should be a non-negative integer. The default value is zero, which allows the user to drag the split-bar so that it butts against the nearest other split-bar or the edge of the window, but not to overlap it. The value may be set at creation time by passing the :min-space-before initarg to make-instance, or any time later by call (setf min-space-before).
If this property, along with min-space-after, is not adequate for constraining the dragging of a split-bar, then an on-drag function could be supplied.
Generic Function, cg package
Arguments: basic-pane
Returns true if its argument (a window of some sort) has an active minimize button and returns nil if it does not. A minimize button iconifies a window.
On Windows, if a help-button is also specified for a window, the minimize button will not appear regardless of the value returned by this function.
The value may be set either by passing a :minimize-button initarg to make-window or by calling (setf minimize-button) any time later. The inspector will also display a minimize-button property for forms and other windows.
On Windows, the minimize and maximize buttons are both drawn whenever either or both are enabled, though if one is disabled then it will be grayed out and inactive. Neither will appear when both are disabled.
Generic Function, cg package
Arguments: window
The smallest height the argument can be made by resizing using the mouse.
This function is not setfable, and is not useful for an application to call. But an application may supply minimum-width and minimum-height methods on its own window classes to specify the minimum size of those classes.
Generic Function, cg package
Arguments: grid-widget-or-section
Returns the minimum allowed size of a grid-row-section, grid-column-section, grid-row, or grid-column, or the default for all sections of a grid-widget. The value may be set at creation time by specifying the minimum-size initarg, or any time later by calling (setf minimum-size). The value is measured in pixels, and refers to the breadth of a row, column, or section.
When the user interactively resizes a grid section or subsection by dragging its right or bottom border, the section will not resize smaller than its minimum-size. Similarly, if a grid-widget or main section is resized smaller (either interactively or programmatically), then any proportional section or subsection within it will not be proportionally resized to smaller than that section or subsection's minimum-size.
The value for a grid-widget is the default for all sections and subsections whose minimum-size property is nil. The value should be a non-negative integer. The default is 12.
The value should be a non-negative integer, or else nil to default to the minimum-size property of the grid-widget. The default is nil.
Generic Function, cg package
Arguments: window
The smallest width the argument can be made by resizing using the mouse.
This function is not setfable, and is not useful for an application to call. But an application may supply minimum-width and minimum-height methods on its own window classes to specify the minimum size of those classes.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-grid-line-color property of a chart-axis. The value may be set at creation time by passing the :minor-grid-line-color initarg, or any time later by calling (setf minor-grid-line-color).
The color that is used to draw minor grid lines for a chart-axis across the body of its chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of light-gray.
This property is used only when the draw-minor-grid-lines property of the chart-axis is true and the minor-grid-line-width property is positive.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-grid-line-dashing property of a chart-axis. The value may be set at creation time by passing the :minor-grid-line-dashing initarg, or any time later by calling (setf minor-grid-line-dashing).
The dashing style that is used to draw minor grid lines for a chart-axis across the body of its chart-widget. The valid values are the same as for the line-dashing property of a graphical-stream. The default value is :dot, which draws a line of closely-spaced small dots.
This property is used only when the draw-minor-grid-lines property of the chart-axis is true and the minor-grid-line-width property is positive.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-grid-line-width property of a chart-axis. The value may be set at creation time by passing the :minor-grid-line-width initarg, or any time later by calling (setf minor-grid-line-width).
The line-width that is used to draw minor grid lines for a chart-axis across the body of its chart-widget. The value should be a non-negative integer. The default value is 1.
Minor grid lines are drawn only when this property is positive and the draw-minor-grid-lines property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
This property has an effect only on the Windows platform.
This property of a chart-axis works just like major-label-angle, except that it affects the labels on the minor tics rather than the major tics. See major-label-angle for more information.
One difference is that the value of minor-label-angle may be nil to default to the major-label-angle. The default is nil.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-label-color property of a chart-axis. The value may be set at creation time by passing the :minor-label-color initarg, or any time later by calling (setf minor-label-color).
The color that is used to draw the label for each minor tic position of a chart-axis in a chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of black.
This property is used only when the draw-minor-labels property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-label-font property of a chart-axis. The value may be set at creation time by passing the :minor-label-font initarg, or any time later by calling (setf minor-label-font).
The font that is used to draw the label for each minor tic position of a chart-axis in a chart-widget. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 10).
This property is used only when the draw-minor-labels property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-label-frequency property of a chart-axis. The value may be set at creation time by passing the minor-label-frequency initarg, or any time later by calling (setf minor-label-frequency).
The number of minor tic positions between successive minor tic labels on a chart-axis in a chart-widget. The value should be a positive integer. The default value is 1, which means that a label is drawn at every minor tic position (when minor tic labels are drawn at all). A value of 2 would draw a label only at every other minor tic position, while 3 would draw a label at every third minor tic position, and so on.
This property is used only when the draw-minor-labels property of the chart-axis is true.
See also minor-label-frequency-offset and major-label-frequency.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-label-frequency-offset property of a chart-axis. The value may be set at creation time by passing the minor-label-frequency-offset initarg, or any time later by calling (setf minor-label-frequency-offset).
The number of minor tic positions, starting at each major tic position, before the first minor tic label is drawn after that major tic position on a chart-axis in a chart-widget. The value should be a non-negative integer. The default value is 0, to potentially draw the first minor tic label after each major tic position at the major tic position itself. (The word "potentially" in the previous sentence alludes to the fact that a minor label is not drawn at major tic position if a major label is drawn there and the overlap-major-and-minor-labels property is true.)
This property is meaningful only when the minor-label-frequency is greater than one. If that property is 4, for example, and minor-label-frequency-offset is 1, then minor tic labels would be drawn at minor tic positions 1, 5, 9 and so on after each major tic position, up to the next major tic position. This property would typically be left at zero, with the minor-label-frequency property determining how densely packed minor tic labels are after each major tic position.
This property is used only when the draw-minor-labels property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: item-axis
Returns the value of the minor-label-min-spacing property of a item-axis. The value may be set at creation time by passing the minor-label-min-spacing initarg, or any time later by calling (setf minor-label-min-spacing).
The minimum distance, measured in pixels, that is maintained between the labels at minor tic positions of an item-axis in a chart-widget. The value should be a non-negative integer, or else nil for no minimum. The default value is 6.
When the value is a number, the distance between minor tic positions will be large enough that there is at least that much space between successive minor tic labels.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: item-axis
Returns the value of the minor-label-wrapping property of a item-axis. The value may be set at creation time by passing the minor-label-wrapping initarg, or any time later by calling (setf minor-label-wrapping).
A boolean value indicating whether labels at minor tic positions of an item-axis in a chart-widget will wrap at spaces. The default value is t. Wrapping will be done only if minor-label-angle property is zero (or nil with a major-label-angle of zero).
If true, then each minor tic label will wrap to a new line of text at every space in the label string. The widget will automatically leave enough room to display the label that requires the most lines of text.
An alternative is to set this property to nil and then embed newline characters in the strings returned by the on-print-minor-label function of the chart-axis.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: item-axis
Returns the value of the minor-tic-increment property of a item-axis. The value may be set at creation time by passing the minor-tic-increment initarg, or any time later by calling (setf minor-tic-increment).
The number of chart items between successive minor tic positions of an item-axis in a chart-widget. The value should be a positive integer. The default value is 1.
When the value is 1, there is a minor tic position for every chart item. This allows a tic mark and/or a tic label and/or a grid line to be drawn for every chart item. If the value were 4, then there could be a tic mark, tic label, or grid line only for every fourth chart item.
See also minor-tics-per-major-tic, draw-minor-tics, draw-minor-labels, and draw-minor-grid-lines.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-tic-length property of a chart-axis. The value may be set at creation time by passing the minor-tic-length initarg, or any time later by calling (setf minor-tic-length).
The length, measured in pixels, of minor tic marks on a chart-axis of a chart-widget. The value should be a non-negative number. The default value is 3.
Minor tic marks are drawn only when this property and minor-tic-width are positive numbers and the draw-minor-tics property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-tic-width property of a chart-axis. The value may be set at creation time by passing the minor-tic-width initarg, or any time later by calling (setf minor-tic-width).
The thickness, measured in pixels, of minor tic marks on a chart-axis of a chart-widget. The value should be a non-negative integer. The default value is 1.
Minor tic marks are drawn only when this property and minor-tic-length are positive numbers and the draw-minor-tics property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the minor-tics-per-major-tic property of a chart-axis. The value may be set at creation time by passing the minor-tics-per-major-tic initarg, or any time later by calling (setf minor-tics-per-major-tic).
The number of minor tic positions per major tic position on a chart-axis in a chart-widget. The value should be a positive integer, or else nil to use a default value. The default value is nil for a value-axis and 1 for an item-axis.
For a value-axis, a value of nil causes the number of tics to be computed automatically such that the increment from one minor tic position to the next is a relatively "round" number. This is done after the major-tic-increment has been determined. For an item-axis, a value of nil simply defaults to 1.
This value is actually the number of minor tic increments from one major tic position to the next. That is, if the value is 5 then 4 minor tic marks will be drawn between the surrounding major tic marks to measure 5 increments from one major tic mark to the next.
A value of 1 means that there are no minor tic positions between major tic positions, resulting in a chart that has only major tic marks, major tic labels, and/or major grid lines.
See also draw-major-tics and draw-minor-tics.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: configuration
If center-all-modal-dialogs-on-screen is false, modal dialogs are, where possible, displayed this amount offset from the top-left of the inner box of the window active when the dialog is displayed. We say `if possible' because the positioning of certain common dialogs is not quite that controllable.
modal-dialog-margin is a property of the configuration class.
Function, cg package
Arguments:
Returns the current modal window if there is one and nil if there is not.
Generic Function, cg package
Arguments: window
Returns true if the argument has been modified since the most recent time it was saved to a file. This function is typically used to determine whether an object needs to be saved.
Whether an object has been modified depends on the type of object. A text-edit-pane has been modified if the text has been changed. A form if any control on the form has been changed (resized, moved, or with different property values). A project is modified if any modules, libraries, subprojects, or files have been added or deleted or themselves changed, or the properties of the project have been changed, or the associated .lpr file has been changed. A grid-widget is modified if its delay-write-cell-value property is true and it has any pending user edits. An object-editor is modified if there are any unsaved edits to its currently-displayed instance.
An application could call (setf modified) on a text-edit-pane (or rich-edit-pane) with a value of nil to declare that the window's contents do not currently need to be saved. This would typically be useful immediately after programmatically placing some initial text into the control for the end user to modify. On the other hand, it is generally unnecessary for an application to set the value to true because this is done internally whenever the content changes.
function, cg package
Arguments:
Returns a list of information about all of the monitors that are present. This includes the coordinate range of each monitor, which can be useful for positioning windows within particular monitors in a multiple-monitor system.
Each element of the list describes one monitor, and so the length of the list indicates the number of monitors.
In CG/JS mode, an exterior box is the only element in the list for a monitor. On Windows there are three additional values. On Windows the four values are:
a box for the exterior of the monitor
a box for the interior of the monitor
a boolean value for whether this monitor is the primary one
a string for the name of the monitor
The exterior covers the entire monitor, while the interior is the portion that applications can use, which basically means that the interior excludes the Windows task bar when there is one on that monitor.
;; Here are examples on Windows and Linux where there are two monitors.
;;
;; On Windows, the output is a list of three element lists:
(monitor-info)
RETURNS
((#<box 0 0 1600 900> #<box 0 0 1600 860> t "\\\\.\\DISPLAY1")
(#<box -2400 -300 0 1200> #<box -2400 -300 0 1200> nil "\\\\.\\DISPLAY2"))CG/JS Notes: Multiple monitors do not pertain to CG/JS, where the whole universe is a single web browser tab. So this always returns just one inner list for one monitor, where the acting screen size is the interior size of the browser tab. This will change, though, if the uses the web browser's commands to zoom (or scale) the whole web page, to reflect the logical screen size that is being scaled to fit into the browser tab's interior.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user presses the back button of the mouse while the mouse cursor is in the interior (client) area of a window or dialog-item. An application may add methods to this generic function to respond to mouse events in these objects.
Microsoft calls this button X button 1. The back button on a ThinkPad will also call this function on Windows.
The arguments work as with mouse-left-down. See that function for more information.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user releases the back button of the mouse while the mouse cursor is in the interior (client) area of a window or dialog-item. An application may add methods to this generic function to respond to mouse events in these objects.
Microsoft calls this button X button 1. The back button on a ThinkPad will also call this function on Windows.
The arguments work as with mouse-left-up. See that function for more information.
Function, cg package
Arguments:
Returns an integer whose bits reflect the state of the mouse buttons and keyboard shift keys at the time that the event currently being handled occurred. A one bit indicates that the button or key was down, and a zero bit that it was not. For example, the expression
(logtest left-mouse-button (mouse-button-state))will return true if and only if the left-mouse-button was down when the event currently being handled occurred. To determine whether a mouse button is down now, use key-is-down-p instead, passing one of the "key" constants vk-lbutton, vk-mbutton, or vk-rbutton (though that works on Windows only).
This function operates per-thread. Specifically, a mouse click that is done on a window that was created in a particular thread will not be included in the value returned by a call to mouse-button-state in any other thread. (An exception is that if there is a single window hierarchy that contains windows from both threads, then the operating system appears to combine the event queues of the two threads, and mouse-button-state will still include mouse clicks and shift key presses that were done in a window of the other thread.)
The following list shows the correspondence of buttons and keys to constants defined in Allegro CL for Windows.
Note: while an event is being handled, the returned value reflects the state at the time that that event occurred. For example, if you call mouse-button-state in an event method for a button-down event, then the returned value will indicate the mouse buttons and shift keys that were pressed when this event occurred, even if the user has released the buttons and keys at the time that the call to mouse-button-state is made.
See also down-keys, down-key-names, key-is-down-p, and key-was-down-p.
Function, cg package
Arguments:
Returns true if the mouse is currently captured, as with capture-mouse or get-shape-box; returns nil if the mouse is not captured.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user presses the left mouse button within double-click-time of another left-click, while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred. If the event occurred in a dialog-item, then this function will be called on the dialog-item and also on its associated widget-window. An application could specialize on whichever object is more convenient (this is typically the dialog-item). In any case, the built-in methods on the widget-window normally should not be overridden, because they implement the widget's built-in click behavior.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: event
Returns true if event is a mouse-event; returns nil otherwise.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user presses the forward button of the mouse while the mouse cursor is in the interior (client) area of a window or dialog-item. An application may add methods to this generic function to respond to mouse events in these objects.
Microsoft calls this button X button 2. The forward button on a ThinkPad will also call this function on Windows.
The arguments work as with mouse-left-down. See that function for more information.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user releases the forward button of the mouse while the mouse cursor is in the interior (client) area of a window or dialog-item. An application may add methods to this generic function to respond to mouse events in these objects.
Microsoft calls this button X button 2. The forward button on a ThinkPad will also call this function on Windows.
The arguments work as with mouse-left-up. See that function for more information.
Generic Function, cg package
Arguments: object buttons mouse-out-object
This generic function is called when the user moves the mouse cursor into a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects. The built-in methods should not be overridden, though, because they perform some standard internal tasks.
object is the window, dialog-item, or hotspot being entered.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
mouse-out-object is the window, dialog-item, or hotspot of the same general type as the object being moved into, if any, that the mouse cursor was over immediately before entering the object.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user presses the left mouse button while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred. If the event occurred in a dialog-item, then this function will be called on the dialog-item and also on its associated widget-window. An application could specialize on whichever object is more convenient (this is typically the dialog-item). In any case, the built-in methods on the widget-window normally should not be overridden, because they implement the widget's built-in click behavior.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position
This generic function is called when the user releases the left mouse button while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
Generic Function, cg package
Arguments: window buttons cursor-position
This generic function is called when the user presses the middle mouse button within double-click-time of another middle-click, while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user presses the middle mouse button while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred. If the event occurred in a dialog-item, then this function will be called on the dialog-item and also on its associated widget-window. An application could specialize on whichever object is more convenient (this is typically the dialog-item). In any case, the built-in methods on the widget-window normally should not be overridden, because they implement the widget's built-in click behavior.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user releases the middle mouse button while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred. If the event occurred in a dialog-item, then this function will be called on the dialog-item and also on its associated widget-window. An application could specialize on whichever object is more convenient (this is typically the dialog-item). In any case, the built-in methods on the widget-window normally should not be overridden, because they implement the widget's built-in click behavior.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: window
Returns or sets the value of a filter for mouse-moved events in the specified window. The default value is nil, to not filter events at all. If activities that use the events (such as dragging operations) get behind, then this can be set to a number of milliseconds. The JavaScript code in the web browser will then send an event only after that many milliseconds have passed since it last sent an event. An exception is that the last event in a series will always be sent, so that the CG application is informed of the final state of that series.
mouse-move-filter, scroll-filter, and wheel-filter are used only when running in a web browser.
This example would cause my-window to never receive a mouse-moved event within a tenth of a second after another one, except when it is the last event in a series.
(setf (mouse-move-filter my-window) 100)Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user moves the mouse cursor within the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects. The built-in methods should not be overridden, though, because they perform some standard internal tasks.
object is the window, dialog-item, or hotspot in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typically left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
Note: the value of the cursor-position argument becomes invalid when mouse-moved returns, in order to avoid the inefficiency of consing position objects for frequent mouse-moved events. If an application needs to keep this argument around to reference it after mouse-moved has returned, it should call copy-position on the value and save the copy rather than the original value.
This cursor-position restriction also applies if an application is still using the deprecated generic function event when the message argument is the value of the constant mouse-moved; in this case the data argument is the position that must not be referenced after the event method returns.
By default, an incoming mouse movement message will not result in a call to mouse-moved if it appears that the mouse cursor has not really moved. See ignore-redundant-mouse-moves.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: object buttons mouse-in-object
This generic function is called when the user moves the mouse cursor out of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects. The built-in methods should not be overridden, though, because they perform some standard internal tasks.
object is the window, dialog-item, or hotspot being exited.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
mouse-in-object is the window, dialog-item, or hotspot of the same general type as the object being moved out of, if any, that the mouse cursor immediately moves into after leaving the object.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position
This generic function is called when the user presses the right mouse button within double-click-time of another right-click, while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user presses the right mouse button while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred. If the event occurred in a dialog-item, then this function will be called on the dialog-item and also on its associated widget-window. An application could specialize on whichever object is more convenient (this is typically the dialog-item). In any case, the built-in methods on the widget-window normally should not be overridden, because they implement the widget's built-in click behavior.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
The default mouse-right-down methods for basic-pane and dialog-item call pop-up-shortcut-menu, which will show a shortcut menu if a shortcut-commands method for the window or widget returns a list of menu-items. An application could make a right-click show a menu by adding a shortcut-commands method, or it could add custom right-click behavior by adding a mouse-right-down method instead. Note that in releases prior to 6.2, the default mouse-right-down methods called pop-up-shortcut-menu only in the IDE, and not in generated standalone applications.
Generic Function, cg package
Arguments: object buttons cursor-position
This generic function is called when the user releases the right mouse button while the mouse cursor is in the interior (client) area of a window, dialog-item, or hotspot. An application may add methods to this generic function to respond to mouse events in these objects.
object is the window, dialog-item, or hotspot in which the event occurred. If the event occurred in a dialog-item, then this function will be called on the dialog-item and also on its associated widget-window. An application could specialize on whichever object is more convenient (this is typically the dialog-item). In any case, the built-in methods on the widget-window normally should not be overridden, because they implement the widget's built-in click behavior.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in "stream coordinates", which are relative to the origin of the possibly scrolled page (canvas) of the window; pixels are the unit of distance unless the window is a scaling-stream. (The origin of a stream is typcially left at 0,0, which indicates the top-left corner of the scrollable page; see stream-origin.)
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons delta-major delta-minor x y
This generic function is called when the user rotates the wheel of the mouse (if it has a wheel). The default behavior is to scroll the window if possible, but an application may add mouse-wheel methods that scroll in some alternate way or interpret the gesture in some arbitrary way unrelated to scrolling. An application should not call mouse-wheel.
mouse-wheel-present may be called to determine if the end user's mouse has a wheel, though mouse-wheel will simply not be called if the mouse does not have a wheel.
The default method will scroll the window vertically if it has a vertical scrollbar, or else horizontally if it has a horizontal scrollbar, and (on Windows) otherwise passes the wheel message to the parent window (if any), resulting in mouse-wheel being called on the parent window. The window will be scrolled by calling user-scroll a number of times for each notch that the wheel was rotated, specifying a :char scroll to scroll by one line-height or character-width each time. The number of times that user-scroll will be called for each notch is equal to the value returned by mouse-wheel-scroll-lines. (If the user has set the mouse wheel to do page scrolls in Control Panel in Windows, then user-scroll will instead be called once to do a page scroll.)
Windows Note:, when defining a mouse-wheel method to do some arbitrary non-scrolling operation, the window should have no scrollbars. The reason is that if the Windows operating system sees that the wheel message handler could have scrolled the window in the requested direction but did not, then the OS sends scroll messages to scroll the window. So there is no way to override the operating system's scrolling behavior for the wheel if either scrollbar is given to the window.
CG/JS Note: When defining a custom mouse-wheel method for a window subclass, for CG/JS mode you will need to define a grab-mouse-wheel method for that subclass that returns true, or else to pass :grab-mouse-wheel t when calling make-window to create each instance of the subclass. The default is nil because a true value overrides the efficient scrolling behavior that's built into the web browser, and it also overrides the typical built-in scrolling behvaior of a two-finger drag on the trackpad.
The arguments are:
buttons works as in mouse-left-down. In addition, some mice that have extra buttons may include the first-x-button or second-x-button bits when those buttons are down.
delta-major is an integer denoting how many notches the user rotated the wheel. Positive values indicate pulling the wheel backward (equivalent to dragging a scrollbar downward or rightward) and negative values indicate pushing the wheel forward (equivalent to dragging a scrollbar upward or leftward).
delta-minor will be a float denoting a fine rotation less than a single notch if the particular mouse wheel supports it, and otherwise will be zero (an integer for backward compatibility). The value will be a float that's either between 0.0 and 1.0 or between 0.0 and -1.0 (inclusive), depending on the direction.
x is an integer indicating the pixel distance from the left edge of the screen to the current mouse cursor position.
y is an integer indicating the pixel distance from the top edge of the screen to the current mouse cursor position.
The following is a sample mouse-wheel method that emulates the default Operating System behavior except that it scrolls the set of lines for each wheel notch (the default is 3) or entire wheel "roll" all at once rather than line one at a time as the default OS behavior does. This will more quickly scroll a window but the scrolling motion will not look as smooth. This example illustrates the various considerations that must be made when writing custom mouse wheel behavior.
(defmethod mouse-wheel ((window my-window) buttons
delta-major delta-minor x y)
(declare (ignore buttons delta-minor x y))
;; This method emulates the OS behavior for scrolling with the mouse
;; wheel, except that it scrolls more quickly (but less smoothly)
;; in one step rather than scrolling each line separately.
(let* ((scroll-lines (mouse-wheel-scroll-lines))
(scrollbars (scrollbars window))
(horizontal (eq scrollbars :horizontal)))
;; Avoid handling this wheel message if the user has disabled
;; the wheel in Control Panel or if the wheel rotation is zero.
(unless (or (eq scroll-lines 0) ;; Wheel disabled
(eq delta-major 0)) ;; No actual wheel rotation
;; If a scrollbar is turned on, then this method
;; interprets the mouse wheel to scroll the window.
(if* scrollbars
;; If the user has set the mouse to scroll by pages
;; in the Control Panel, then scroll by a page for
;; a wheel "roll" of any number of notches.
then (if* (eq scroll-lines t)
then (user-scroll window
(if* (minusp delta-major)
then (if horizontal :left :up)
else (if horizontal :right :down))
:page)
;; Otherwise scroll by the number of lines
;; per notch specified in Control Panel (default 3).
;; Do this in one jump for a quick scroll, unlike
;; the OS which would call user-scroll once for each
;; line to be scrolled.
else (with-positions (pos1)
(scroll
window
(if* horizontal
then (nmake-position
pos1
(* scroll-lines
delta-major
(space-width window))
0)
else (nmake-position
pos1 0
(* scroll-lines
delta-major
(line-height window)))))))
;; This window has no scrollbars, so pass this message on.
;; The default method will pass the message to the parent.
else (call-next-method)))))Function, cg package
Arguments:
On Windows, this function returns true if and only if a mouse that has a wheel is installed. This function may be useful for an application that adds mouse-wheel methods to implement custom mouse-wheel behavior.
This function works whenever the operating system is Microsoft Windows, even when running in CG/JS mode, but should not be called in other operating systems.
Function, cg package
Arguments:
This function returns the number of lines that a mouse wheel should scroll for each notch that it is rotated, or t if a wheel "roll" of any number of notches should do a page scroll. On Windows, this is a global Control Panel setting that defaults to 3.
A custom mouse-wheel method that does scrolling could call this function to help decide how far to scroll.
See also mouse-wheel-present.
Generic Function, cg package
Arguments: grid-subsection
This function returns the value of the movable property of its argument. This property determines whether the user may drag the grid-column or grid-row to a new position.
A movable grid-row may be moved interactively only by clicking it in its cells that also lie in columns that are instances of row-selecting-column-mixin. Likewise, a movable
The setf of this function may be called at runtime to change the movable status of a row or column.
movable is a property of the grid-subsection, grid-column, row-header-column, grid-row, and column-header-row classes.
Generic Function, cg package
Arguments: stream offset
Moves the current position of stream by offset which must be a position (see make-position). stream should be a cg-stream but may not be a text-edit-window or a text-edit-pane.
See also move-by-x-y.
Generic Function, cg package
Arguments: stream x y
Moves the current position of stream by x in the horizontal direction and y in the vertical direction (positive is down). stream should be a cg-stream but may not be a text-edit-window or a text-edit-pane.
Contrast with move-by, where the x and y values are passed as a position object.
Generic Function, cg package
Arguments: outline &key extend cursor-only
Selects the outline-item that is just below the one that is currently selected, if any.
If extend is true and the multiple-selections property of the outline is true, then the item that had been selected will remain selected as the new item is added to the list of selected items.
If cursor-only is true, then only the keyboard focus is moved, without changing which item is selected.
This function could be called directly for an interactive command to move to the next item, typically passing extend as true if the shift key is down. The down arrow key has this functionality built in, though other keystrokes may be desired.
Generic Function, cg package
Arguments: outline item-value new-parent-value &key no-redisplay
Moves the outline-item on outline whose value is item-value so that it is a subitem of the item whose value is new-parent-value. Does not redisplay outline if no-redisplay is specified true.
Function, cg package
Arguments: stream offset
Sets the stream-origin of stream to a new position relative to its current position. offset must be a position object (such as returned by make-position) that specifies the rightward and downward distances by which to move the origin from its current position. stream should be a cg-stream.
To instead move the origin to a new absolute position on the stream's page, call (setf stream-origin).
Generic Function, cg package
Arguments: row-or-column new-index
This function programmatically moves a row or column to a new position, specified by new-index, amongst the rows or columns of its section.
Generic Function, cg package
Arguments: graphical-stream position
Establishes the current position of a graphical-stream from which a line or a text string may be drawn.
This function accepts a position object (see make-position), whereas move-to-x-y accepts individual x and y coordinates.
See ncurrent-position for more information.
Generic Function, cg package
Arguments: graphical-stream x y
Establishes the current position of a graphical-stream from which a line or a text string may be drawn.
This function accepts individual x and y coordinates (integers), whereas move-to accepts a position object.
See ncurrent-position for more information.
Generic Function, cg package
Arguments: outline &key extend cursor-only
Selects the outline-item that is just above the one that is currently selected, if any.
If extend is true and the multiple-selections property of the outline is true, then the item that had been selected will remain selected as the new item is added to the list of selected items.
If cursor-only is true, then only the keyboard focus is moved, without changing which item is selected.
This function could be called directly for an interactive command to move to the previous item, typically passing extend as true if the Shift key is down. The up arrow key has this functionality built in, though other keystrokes may be desired.
Generic Function, cg package
Arguments: window position
Moves window so its exterior top left is at position (in parent device coordinates). Sometimes this may not be possible, and window will be moved to another position. Returns the actual position window was moved to, or nil if window was not moved.
Generic Function, cg package
Arguments: window other-window
Places window behind (in the occlusion stack) other-window, which must be a sibling of window. Note that the function affects which window is above the other. It does not affect the location of window.
Function, cg package
Arguments: window &key (overlap-x (width window)) (overlap-y (height window))
If window is not entirely contained within the scrollable extent of its parent, moves the window as far as necessary so that it is. This function is used by forms to prevent losing a component by accidentally dragging it completely off of the form.
overlap-x is the amount in pixels by which the window must horizontally overlap the visible interior of its parent. The default is the width of the window, to make the entire window visible within its parent if possible. A smaller positive value would make the window partly visible (so that it can be spotted by the user) without showing more of the window than necessary if it might otherwise obscure other important content in the parent.
Similarly, overlap-y is the amount in pixels by which the window must vertically overlap the visible interior of its parent. The default is the height of the window, to make the entire window visible within its parent if possible.
Function, cg package
Arguments: window offset
Moves window by offset, which must be a position. It may not be possible to move window to that location, in which case window is moved to some other location (typically near the desired location) or not moved at all. Returns the actual new position of the window exterior top left, or nil if no movement was possible.
Generic Function, cg package
Arguments: item-list
Returns true if the items of item-list will be arranged into multiple columns when needed. This is done only when the items do not fit vertically into a single column. The column-width property determines the actual width of the columns.
The multi-column-p property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :multi-column-p initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
multi-column-p is a property of the multi-item-list and single-item-list classes.
Generic Function, cg package
Arguments: widget scroll-pos
Scrolls widget, which must be a multi-picture-button control, to scroll-pos. See the description of the multi-picture-button class/control.
Generic Function, cg package
Arguments: configuration
Returns the value of the multi-picture-button-scroll-interval property of configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
The value is the number of milliseconds between successive scroll increments of a multi-picture-button as the mouse button is held down after clicking a multi-picture-button scroll arrow. Initially 200. This internally uses the built-in cg-timer.
multi-picture-button-scroll-interval is a property of the configuration class.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: printer
Returns the value of the multicolor property of printer. This property tells whether the printer is in multicolor mode rather than monochrome mode (black and white only). This property will always be nil if the printer is not a color printer, even if the :multicolor initarg to open-stream was specified as true when creating the printer stream.
An application may check the value of this property to determine whether it may print colors on the printer that the user has selected (along with various printer options) in the print job dialog that appears by default when opening a printer stream.
This property may be specified with the :multicolor initarg to open-stream when creating a printer stream, though a particular printer driver may or may not pay any attention to the value. multicolor is a property of the printer class.
Note: this generic function is not setf'able.
Generic Function, cg package
Arguments: widget button-info
This method is called when the mouse cursor moves into the button specified by button-info of the multi-picture-button specified by widget. Only add before or after methods since the default method does necessary work.
See the description of the multi-picture-button class/control.
Generic Function, cg package
Arguments: widget button-info
This method is called when the mouse cursor moves out of the button specified by button-info of the multi-picture-button specified by widget. Only add before or after method since the default method does necessary work.
See the description of the multi-picture-button class/control.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the multiple-selections property of the argument. This property determines whether the user can select multiple values simultaneously. multiple-selections is a property of the outline, dropping-outline, multi-picture-button, and list-view classes.
Whether the value property of one of these widgets is a single value or a list of values depends on this multiple-selections property and on the widget class. For an outline (or dropping-outline), if multiple-selections is nil then the value of the widget will be a single value (or nil if no outline-item is selected), and if multiple-selections is true then the value of the widget will be a list of zero or more values. On the other hand, the value of a list-view or multi-picture-button is always a list of zero or more values, even when multiple-selections is nil.
Generic Function, cg package
Arguments: standard-object
Returns the value of the name property of the argument. The object may be any Common Graphics object that has a name property. Objects may be found from their names by passing the names to various finder functions, such as:
The name should be a symbol, so that finder functions can find the object by using eq tests on the name. To ensure that the finder functions find the expected objects, any objects that co-exist within some context that is passed to a finder function (such as the parent window passed to find-component) should always be given mutually unique names (and so any two components on the same parent window should never have the same name, for example). If the finder-function has no context (such as find-timer), then the names should be globally unique among objects of that type (such as all timers).
When an object that has a name property is created without specifying a :name initarg value, a default name is assigned. In particular, when placing components onto form windows in the IDE, mutually unique default names are assigned by appending sequential numbers to the name of the class of each component (resulting in names such as :picture-button-1 followed by :picture-button-2).
Generic Function, cg package
Arguments: object
Returns the name-string (the name converted to a string) of project. Do not confuse this function with namestring (no hyphen) which returns the namestring of a pathname.
Generic Function, cg package
Arguments: graphical-stream
Returns the symbol for the current named gradient, if any, and otherwise nil. The graphical-stream would be one that was passed to with-named-gradient or set-named-gradient.
This generic function is implemented only on Windows and JavaScript/HTML.
Function, cg package
Arguments: box offset
Returns box after modifying it by offsetting it by offset, which must be a position object (as created by make-position). Thus, the top and bottom of box are increased by the position-y of offset while the left and right are increased by the position-x component). Contrast with box-move which returns a new box and does not modify its box argument.
Generic Function, cg package
Arguments: stream event-number button-state data frame-section
This generic function is obsolete and kept for backward compatibility only. Starting in version 5.0, events are handled somewhat differently than in 3.0.2. Instead of specializing nc-event, you should specialize the new generic function named after the message, such as nc-right-mouse-down and nc-mouse-moved. These were only constants in 3.0.2 (corresponding to the message argument to nc-event) but they are now constants and generic-functions. nc-event is still called, as in 3.0.2, but it simply dispatches to the appropriate new function. All these functions take the same arguments as nc-event except the event-number argument.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user presses the left mouse button within double-click-time of another left-click, while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user presses the left mouse button while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: object buttons cursor-position frame-section
This generic function is called when the user releases the left mouse button while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
object is the window, dialog-item, or hotspot in which the event occurred. If the event occurred in a dialog-item, then this function will be called on the dialog-item and also on its associated widget-window. An application could specialize on whichever object is more convenient (this is typically the dialog-item). In any case, the built-in methods on the widget-window normally should not be overridden, because they implement the widget's built-in click behavior.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user presses the middle mouse button within double-click-time of another middle-click, while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user presses the middle mouse button while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user releases the middle mouse button while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called whenever the user moves the mouse cursor within the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
Note: the value of the cursor-position argument becomes invalid when nc-mouse-moved returns, in order to avoid the inefficiency of consing position objects for frequent nc-mouse-moved events. If an application needs to keep this argument around to reference it after nc-mouse-moved has returned, it should call copy-position on the value and save the copy rather than the original value.
This cursor-position constraint also applies to the deprecated generic function nc-event when the message argument is the value of the constant nc-mouse-moved; in this case the data argument is the position which will become invalid when the nc-event method returns.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user presses the right mouse button within double-click-time of another right-click, while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user presses the right mouse button while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: window buttons cursor-position frame-section
This generic function is called when the user releases the right mouse button while the mouse cursor is in the frame (border) area of a window. An application may add methods to this generic function to respond to mouse events in its windows, though frame-area events are usually left to the operating system.
window is the window in which the event occurred.
buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest left-mouse-button buttons) will return true if and only if the left mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
cursor-position is a position object indicating the location of the mouse cursor when the event occurred. It is in pixel coordinates relative to the upper-left corner of the screen.
frame-section is a keyword indicating the general area of the frame in which the event occurred. The value will be one of the following symbols:
:left
:top-left
:top
:top-right
:right
:bottom-right
:bottom
:bottom-left
:caption
:client
:error
:nowhere
:grow-box
:horizontal-scrollbar
:vertical-scrollbar
:menu
:system-menu
:minimize
:maximize
:transparent
:object
:close
:help
Thus, :top-left, for example, denotes the area at the upper left where the window's left and top edges can be stretched, while :maximize refers to the gadget that maximizes the window.
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: window position
Like caret-position, returns the current position for the caret of window, but accepts a dummy position which it fills in and returns to avoid cons-ing.
Generic Function, cg package
Arguments: stream box
Modifies and returns box (as the first of two returned values) to be the clipping box of stream. stream should be a cg-stream but may not be a text-edit-window or a text-edit-pane.
This is the destructive version of clipping-box, taking a box argument to be modified rather than creating and returning a new box. See the description of clipping-box for more information and for details of the second returned values.
Platform note: the box that is returned will exclude any part of the window that happens to be covered by other windows on the Microsoft Windows platform.
Function, cg package
Arguments: to-box from-box
Modifies to-box to be a copy of from-box and returns it. Contrast with copy-box, which takes a single box argument and returns a new box which is a copy of it.
Function, cg package
Arguments: to-pos from-pos
Modifies to-pos to be a copy of from-pos and returns it. Contrast with copy-position, which takes a single position argument and returns a new position which is a copy of it.
Generic Function, cg package
Arguments: graphical-stream position-to-return
Modifies position-to-return to contain the current position of the specified graphical-stream, and returns it. position-to-return must be a position object. See make-position.
The current position is the position from which several functions will draw a line or text. These functions include draw-to as well as the Common Lisp stream output functions such as format and print. These functions also set the current position to the place where they finished drawing. An application may also set the current position by calling move-to.
Other drawing functions accept arguments for all relevant positions, and so do not use or modify the current position.
When drawing text, the current position indicates the upper-left corner of the next character to be drawn. A stream output function leaves the current position at the upper-right corner of the last character drawn, ready to draw further characters just after it.
Generic Function, cg package
Arguments: window-or-screen position
Modifies position to be the cursor-position of window-or-screen and returns it. The screen is the value returned by (screen *system*). See screen and *system*.
Contrast with cursor-position, which returns a new position.
CG/JS Note: In CG/JS mode, this will return a zero-zero position if the mouse has not yet been moved after the application has started up, because CG can know the position only from mouse movement messages.
Function, cg package
Arguments: &optional graphical-stream
Prepares a graphical-stream for drawing on a fresh page.
If graphical-stream is a printer stream, then the physical printer is instructed to eject the current sheet of paper and begin drawing on another one. The current-position-x of the stream is also set to the stream's left-margin, and the current-position-y is set to the top-margin. This allows text stream output to continue at the upper-left margin of the new page.
For other graphical streams (windows, the screen, and bitmap-streams), new-page simply calls clear-page to draw a blank background on which to draw content.
Generic Function, cg package
Arguments: window
This function is used by the File | New menu-item of the default menu-bar that may be interactively attached to a form. In the IDE, it demonstrates a typical "New" command for creating a text editor but this function is not available in a runtime image. A custom application that implements a "New" command will need to supply its own code for such a command instead, but it may be useful to model after the default menu-bar's example. Here is the code for the new-text-editor example (note: this code changed, adding values for the width and height arguments, between release 6.2 and release 7.0):
(in-package :cg)
(defmethod new-text-editor ((window basic-pane))
;; Called by the default "New" menu-item added to a form.
(make-window (gensym-sequential-name :editor)
:device 'text-edit-window
:parent window
:width (floor (interior-width window) 1.2)
:height (floor (interior-height window) 1.2)))See also save-text-file, save-as-text-file, and open-text-file.
Generic Function, cg package
Arguments: section
Returns the next section after the given section, and the index within that section as a second value. If the last section is passed in, then nil is returned.
Function, cg package
Arguments: section subsection &optional count
Returns the next subsection in the given section after the given subsection, and the index within that subsection as a second value. If the last subsection is passed in, then nil is returned.
Generic Function, cg package
Arguments: window &key owned-p states for-focus
If owned-p is nil (the default), returns the window that comes just after the specified window in the front-to-back occlusion order of the child windows of the parent window of the specified window, if any, and otherwise returns nil.
If owned-p is true, returns the window that comes just after the specified window in the front-to-back occlusion order of the non-child owned windows of the owner window of the specified window, if any, and otherwise returns nil.
If states is non-nil, then it should be a list of window state symbols, and windows whose state is not in this list are skipped. If nil (the default), then these windows are not skipped. Valid symbols for this list are :normal, :shrunk, :icon, and :maximized. See state.
If for-focus is true, then windows whose events are currently disabled (see enable-events) are skipped, and "static" control windows are skipped as well. ("Static" control windows include static-text-pane, static-picture-pane, and group-box-pane.) If nil (the default), then these windows are not skipped. Such windows do not handle any keyboard events, so passing this argument as true may be useful for finding a window to move the keyboard focus to by calling set-focus.
See also front-window and windows.
Generic Function, cg package
Arguments: window-or-screen box
Returns box after modifying it to be equal to the exterior box of window-or-screen. The box is relative to the upper-left corner of the "page" of the parent window, or of the screen if there is no parent window. (A "page" is the logical canvas of a window, on which drawing is done and which is sometimes scrollable. So if the parent window is not scrolled, then the box is relative to the upper-left corner of the parent's interior.) The unit of measurement is pixels.
Contrast with exterior, which creates and returns a new box object.
Function, cg package
Arguments: window-or-screen position
Returns position after modifying it to be equal to the position of the top-left corner of the exterior box of window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*.
position must be a position. See make-position.
Contrast with exterior-top-left, which creates and returns a new position object.
Generic Function, cg package
Arguments: stream position
Modifies position so that it is the fill-texture origin of stream. This is the destructive version of fill-texture-origin.
Generic Function, cg package
Arguments: stream fontmetrics
Modifies as necessary and returns the specified fontmetrics object so it describes the current font of stream.
This destructive version of fontmetrics may be useful for avoiding consing a lot of fontmetrics objects if frequent calls are required; this could be done by calling make-fontmetrics just once to create a single utility fontmetrics object, and then passing it to nfontmetrics each time a call to this function is needed (using the object temporarily within a single process where re-entrancy is not an issue).
See also Text and Fonts in cg-drawing.html.
Generic Function, cg package
Arguments: window-or-screen old-box &optional scroll-p cursor first-corner
This is like get-box, except with an additional old-box argument that avoids consing a new box.
old-box should always be a box object, typically allocated by with-boxes to avoid consing. This function will then fill in that box and return it, instead of creating a new box.
Generic Function, cg package
Arguments: window-or-screen old-box &optional scroll-p cursor
This is like get-fixed-box, except with an additional old-box argument that works as in nget-box to avoid consing a box.
Generic Function, cg package
Arguments: window-or-screen start-position old-position &optional scroll-p cursor
This is like get-line, except with an additional old-position argument that avoids consing a new position.
old-position should always be a position object, typically allocated by with-positions to avoid consing. This function will then fill in that position and return it, instead of creating a new position.
Generic Function, cg package
Arguments: window-or-screen old-position &optional scroll-p cursor
This is like get-position, except with an additional old-position argument that works as in nget-line to avoid consing a new position.
The other arguments work as in get-line.
Generic Function, cg package
Arguments: window-or-screen old-box draw-fn erase-fn &optional scroll-p cursor first-corner
This is like get-shape-box, except with an additional old-box argument that avoids consing a new box.
old-box should always be a box object, typically allocated by with-boxes to avoid consing. This function will then fill in that box and return it, instead of creating a new box.
Generic Function, cg package
This is like get-shape-box, except with an additional old-box argument that works as in nget-shape-box to avoid consing a new box.
Generic Function, cg package
Arguments: window-or-screen start-position old-position draw-fn erase-fn &optional scroll-p cursor
This is like get-shape-line, except with an additional old-position argument that avoids consing a new position.
old-position should always be a position object, typically allocated by with-positions to avoid consing. This function will then fill in that position and return it, instead of creating a new position.
Generic Function, cg package
Arguments: window-or-screen box
Returns box after modifying it to equal the interior box of window-or-screen. The box is relative to the upper-left corner of the "page" of the parent window, or of the screen if there is no parent window. (A "page" is the logical canvas of a window, on which drawing is done and which is sometimes scrollable. So if the parent window is not scrolled, then the box is relative to the upper-left corner of the parent's interior.) The unit of measurement is pixels.
The screen is the value returned by (screen *system*). See screen and *system*. For the screen, the interior is the area that excludes the taskbar.
box must be a box. See make-box.
Contrast with interior which creates a new box to return.
Function, cg package
Arguments: window-or-screen position
A destructive version of interior-top-left. The position argument is modified to be the position of the top left corner of the interior of window-or-screen and then returned. The screen is the value returned by (screen *system*). See screen and *system*. position must be a position. See make-position. For the screen, the interior is the area that excludes the taskbar.
Function, cg package
Arguments: box left top right bottom
A destructive version of make-box. The box argument is modified to be the box specified by the remaining arguments returned.
Function, cg package
Arguments: box top-left bottom-right
A destructive version of make-box-from-corners. The box argument is modified to be the box specified by the remaining arguments and returned. Both top-left and bottom-right must be position objects specifying the corresponding positions of the desired box.
Function, cg package
Arguments: box left top width height
A destructive version of make-box-relative. The box argument is modified to be the box specified by the remaining arguments and returned. Equivalent to nmake-box with arguments left top (+ left width) (+ top height).
Function, cg package
Arguments: box top-left width height
A destructive version of make-box-relative-from-corner. The box argument is modified to be the box specified by the remaining arguments and returned. Top-left must be a position. Equivalent to nmake-box with arguments (position-x top-left) (position-y top-left) (+ (position-x top-left) width) (+ (position-y top-left) height).
Function, cg package
Arguments: pos x y
A destructive version of make-position. The first argument must be a position object. It is modified to have the coordinates specified by the x and y arguments (whose values must be fixnums) and then returned.
Generic Function, cg package
Arguments: dialog-item
Returns the mouse cursor image to be used while doing a drag-and-drop whenever the mouse cursor is over dialog-item and dropping onto that dialog-item is not allowed. (droppable-p methods determine where dropping is allowed.)
An application typically would not need to call this generic function, but may define methods on it to customize the mouse cursors that are used by drag-and-drop. The returned value should be either an instance of the cursor class or a mouse cursor-handle.
The default method returns the mouse cursor handle which is the value of the variable no-drop-cursor. This cursor shows a red circle with a diagonal line through it, indicating that it is not possible to drop the dragged value onto this dialog-item.
drag-cursor and drop-cursor return mouse cursors to use at other times during a drag.
Generic Function, cg package
Arguments: editable-text
Returns whether an editable-text or multi-line-editable-text widget will let a web browser's built-in text-editing control draw its focus rectangle when it has the keyboard focus. The value can be set by calling the setf of this function, or at creation time by passing the :no-focus-box initarg.
That built-in focus box can appear heavy-handed in some cases. CG's grid-widget turns it off for the editable-text that's used for editing text in a grid cell, because it's redundant with the cell focus box that's drawn by CG (and the cell's borders).
Generic Function, cg package
Arguments: trackbar
Returns the value of the no-pointer property of its argument. If the value of this property is true, no pointer indicating the current value is displayed.
The no-pointer property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :no-pointer initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
no-pointer is a property of the trackbar class.
Generic Function, cg package
Arguments: object
Returns a list of the non-event properties of object. The non-event properties are the ones that appear on the property pane of an inspector window when object is being inspected. The event properties are listed on the events pane (and are not included in the returned list). Internal properties are listed on the internals pane (and they too are not included in the returned list).
function, cg package
Arguments: window
Returns the exterior that a window has or would have when its state is :normal. This may be useful, for example, for finding the official window size to save with an application's user preferences even if the window is maximized or iconized when preferences are saved.
When the state of the window is either :normal or :shrunk, the returned box is the same as the one returned by exterior. When the state is :maximized or :icon, the returned box is the exterior that the window would have if its state were changed to :normal, which is generally the exterior that it had when the state was most recently :normal.
The returned value is a box, as made with make-box. The returned box should not be modified, because the box object is cached and reused to avoid consing.
Generic Function, cg package
Arguments: text-edit-pane
Returns the value of this property of the argument and can be set with setf. If true, the selection-changed method is called when the selection in the window changes. The default method does little but you can add before or after methods as needed.
notify-when-selection-changed is a property of the multi-line-editable-text and text-edit-pane classes.
Generic Function, cg package
Arguments: split-bar
Returns the now-dragging property of a split-bar widget.
This property indicates whether the split-bar is currently being dragged interactively by the end user, returning true if that is so and nil otherwise. The value should not be set by an application, but the value could be read in an on-change function, for example, to determine whether the new value is an intermediate value during a drag, rather than a final value at that is being set programmatically or at the end of a drag.
It could also be called in an on-redisplay function to draw the split-bar differently while it is being dragged.
See also now-under-mouse.
Generic Function, cg package
Arguments: split-bar
Returns the now-under-mouse property of a split-bar widget.
This property indicates whether the split-bar is currently under the mouse cursor but not being dragged, returning true if that is so and nil otherwise. The value should not be set by an application, but the value could be read in an on-redisplay function, for example, to draw the split-bar differently when it is under the mouse. The related property now-dragging will be true during a drag.
Function, cg package
Arguments: stream box
Returns box after modifying it to be the box representing the whole page of stream, relative to the current origin. This is the entire area that can be drawn onto or scrolled into the visible area. stream should be a cg-stream.
If the stream-origin of a window has not been changed from its usual position at 0, 0, then the left and top of the npage-box will each be zero, and the right and bottom will be the page-width and page-height of the window. Otherwise the origin position is subtracted from that box to obtain the npage-box.
This is the destructive version of page-box, which creates and returns a new box object. See make-box.
Function, cg package
Arguments: position1 position2
Returns position1 after modifying it to be (position+ position1 position2). This is the destructive version of position+, which returns a new position object.
The returned position has x value
(+ (position-x position1) (position-x position2)) and y value
(+ (position-y position1) (position-y position2))Function, cg package
Arguments: position1 position2
Returns position1 after modifying it to be (position- position1 position2). This is the destructive version of position-, which returns a new position object.
The returned position has x value
(- (position-x position1) (position-x position2)) and y value
(- (position-y position1) (position-y position2)).Function, cg package
Arguments: position theta
The destructive version of position-rotate. Modifies position so that its value is the original position rotated theta degrees clockwise about the origin (with the x and y components rounded to make them integers).
Function, cg package
Arguments: position matrix
The destructive version of position-transform. The position argument is modified to be the result.
This function transforms the given position with the supplied matrix, which is a 2 by 2 array (or larger 2-dimensional array -- extra cells of the array are ignored). If the elements of matrix are floats, the returned (and modified) position will have rounded whole number components. The transform works as follows:
xnew = A(0,0)*xold + A(0,1)*yold
ynew = A(1,0)*xold + A(1,1)*yoldFunction, cg package
Arguments: position scale-x scale-y
The destructive version of position*. Modifies position so that its x component is
(round (* (position-x position) scale-x))and its y component is
(round (* (position-y position) scale-y))Generic Function, cg package
Arguments: stream position
Returns position after modifying it to be the position to which stream has been scrolled relative to the page top left. This is the destructive version of scroll-position.
An application may override the default method of this and several other generic functions in order to implement a custom scrolling scheme that scrolls by logical picture objects rather than by pixels. See the source code of the example entitled 'Scrolling by arbitrary objects rather than pixels' in the Examples tab of the Navigator dialog for a complete example. More on this point and a list of the relevant generic functions can be found on the horizontal-scroll-bar and vertical-scroll-bar pages.
Generic Function, cg package
Arguments: stream position
This function is like stream-origin, except that it destructively modifies and returns the position argument (which must be a position object created by make-position), rather than consing a new position. This may be useful to avoid garbage creation if called frequently. stream should be a cg-stream.
Unlike stream-origin, nstream-origin is not setfable. See stream-origin for further information.
Generic Function, cg package
Arguments: stream string start end top-left bottom-left top-right bottom-right
Use of the function is deprecated. Use stream-string-width and line-height instead.
Modifies and returns as multiple values the last four arguments (top-left, bottom-left, top-right, bottom-right), which should all be position objects as created with make-position.
The returned values provide information about the size of string on stream. stream should be a cg-stream.
The new values are:
top-left: (make-position 0 (line-height stream))
bottom-left: (make-position 0 0)
top-right:
(make-position (stream-string-width stream string start end) (line-height stream))
bottom-right:
(make-position (stream-string-width stream string start end) 0)
See line-height and stream-string-width. The returned values are not meaningful if string (or the substring specified by start and end) contains newline characters.
The results describe the area taken up by string (or the substring specified by start and end) if it were printed to stream using the font of stream as returned by font.
Because this function returns the same information as line-height and stream-string-width (though in a somewhat different format), its use is deprecated. We recommend you use line-height and stream-string-width instead.
The function stream-string-corners is the non-destructive version of this function.
Generic Function, cg package
Arguments: stream string position &optional start end
Use of this function is deprecated. Use stream-string-width instead.
Modifies and returns position so that it is the amount by which the current position of stream would move if string (or the substring of string determined by start and end if those arguments are supplied) were printed onto it by princ using the default font of stream (as returned by font).
stream should be a cg-stream.
The result is not meaningful if string contains newline characters.
This function is not in fact particularly useful and we recommend against using it. The position-x of position will be the value returned by stream-string-width called with the stream, string, start, and end arguments. position-y of position will be 0, so the same information can be determined by a call to stream-string-width and calling that function is recommended over using this one.
This is the destructive version of stream-string-size.
Function, cg package
Arguments: n parent-stream &key owned-p states
Returns the nth window on parent-stream. Counting starts from 0.
parent-stream may be either a window or the screen (the value of (screen *system*), see screen and *system*).
If owned-p is nil, then only child windows are considered. If it is true, then only owned windows of parent-stream that are not also child windows of parent-stream are considered. Only top-level windows can have owned windows that are not also their children.
States should be list of window states, that is one or more of (:normal :maximized :shrunk :icon), to consider when looking at sub-windows. If nil, then all sub-windows are considered. Otherwise, only considers the sub-window if its state is a member of states.
function, cg package
Arguments: value
Returns the null string if value is nil, and otherwise returns what princ-to-string would return for value. This utility function is provided for specifying as the data-read-converter for a grid-column, so that null cell values will show blank cells rather than printing "nil".
Generic Function, cg package
Arguments: stream
stream can be a text-edit-window, text-edit-pane, or multi-line-editable-text component or an outline control. Returns the number of text lines currently contained in the window or component.
Generic Function, cg package
Arguments: text-edit-pane
The function returns the paragraph numbering style of the selected text of text-edit-pane. The possible values are :plain or :bullets.
The setf function sets the paragraph numbering style of the selected text of text-edit-pane. value should be either :plain or :bullets.
text-edit-pane must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: string
Attempts to return whether doing a Lisp read on the specified string would return a number, rather than a symbol or other type of object. The returned boolean value (t or nil) may not be correct in all cases. Some CG applications use this to avoid interning symbols from unknown interactive user input when reading input as numbers, and so it may be useful elsewhere.
Generic Function, cg package
Arguments: window-or-screen box
Returns the bounding box of all monitors in the system on newer versions of Windows, when passed the screen. On Windows with multiple monitors, the returned box will be the bounding rectangle for all monitors when window-or-screen is the screen. Otherwise this function returns the same box as nexterior.
window-or-screen should be either a window or the screen. For a window this is the same as calling nexterior.
box should be a box object (see make-box) as created with make-box or with-boxes. This box object is modified and returned.
When window-or-screen is the screen, this function simply calls make-box-relative on the values returned by virtual-screen-left, virtual-screen-top, virtual-screen-width, and virtual-screen-height.
See also virtual-exterior, usable-left, usable-top, usable-width, and usable-height.
Generic Function, cg package
Arguments: window box
Returns box after modifying it to be the visible-box of window. This is the destructive version of visible-box. The visible box is the box that indicates what portion of the window's page is currently visible within the window, considering its scroll-position and size. The visible box changes when a window is scrolled or resized.
Function, cg package
Arguments: window position
Returns position after modifying it to be the position of the top left corner of the visible-box of window. This is the destructive version of visible-box-top-left. The visible box is the box that indicates what portion of the window's page is currently visible within the window, considering its scroll-position and size. The visible box changes when a window is scrolled or resized.
Generic Function, cg package
Arguments: object &optional package
Returns the name of a class derived from an arbitrary object. When a command that acts on a class (such as graph-subclasses) is invoked in the Allegro development environment, the default selected-class method finds a class to apply the command to by calling object-class on the selected-object of the selected window. Object-class may return nil if a class cannot be derived in some reasonable way from the object. Object-class is bypassed if there is a more specific selected-class method for a particular command and selected window; these more specific methods sometimes exist when it is not sufficient to funnel through the general selected-object in order to derive a selected-class for the window.
Generic Function, cg package
This symbol is exported only because it is the name of the object-editor class. The operator with the same name is not for use by applications.
Generic Function, cg package
Arguments: object-editor
This function is called by the :delete-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It removes the currently-displayed instance (see current-instance) from the set of instances that the specified object-editor (an instance of object-editor) is editing. If the edited-class is a persistent class, then db.ac:delete-instance is also called on the instance to remove it from the AllegroCache database. (This function and button are probably useful only for persistent classes.)
The dialog will then display the previous instance that is in the internal sorted list, if any, and otherwise the next instance, if any. (See display-special-instance.)
Generic Function, cg package
Arguments: object-editor
This function is called by the :new-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It creates a new instance of the edited-class of the object-editor and calls display-instance to display it.
Generic Function, cg package
This symbol is exported only because it is the name of the object-editor-pane class. The operator with the same name is not for use by applications.
Generic Function, cg package
Arguments: object-editor
This function is called by the :revert-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It undoes any modifications that the user has made to the currently-displayed instance if they have not yet been saved by a call to object-editor-save. It does this by simply calling display-instance on the current-instance of the object-editor (an instance of object-editor) to overwrite any modified values in the widgets.
Note that an automatic save might occur before the user realizes it if the save-on-clear-focus or the save-on-new-widget-value property is true. Pressing the Enter key also does a save if the :save-button widget (a default-button) is included.
Generic Function, cg package
Arguments: object-editor
This function is called by the :save-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It writes any values that the user has modified in the widgets of the object-editor (an instance of object-editor) back into the slots of the current-instance that the object-editor is displaying. If object-editor-revert is called first to undo the current edits, then they will never be saved.
This function is called automatically whenever a new instance is displayed, to save the previously-displayed instance first. It is also called when the keyboard focus is moved from the object-editor if its save-on-clear-focus property is true. It is called anytime the user has modified a widget if the save-on-new-widget-value property is true.
The modified property of an object-editor will be true when there are unsaved edits to the currently-displayed instance.
Generic Function, cg package
Arguments: object-editor
This function is called by the :search-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It allows the user to search for an arbitrary string in a slot (or all slots) of the edited-instances of the object-editor (which must be an object-editor). It does this by displaying a modal dialog where the user may enter the search string and select the slot to search. Multiple matches are presented in a list where the user can select a matching instance to display.
A match is found whenever the search string is a subsequence of the stringified slot value. (When the value of a searched slot is not a string, then prin1-to-string is used to produce a string to test.) The test is char= if the Case Sensitive check-box is checked, and char= otherwise.
Successive invocations of this dialog will initially display the previous matches. This allows the user to display another matching instance without redoing the search.
Generic Function, cg package
Arguments: object-editor
This function is called by the :select-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.
It allows the user to select an instance to display from a series of pop-up-menus. It does this by calling pop-up-menus-for-many-sorted-choices, which handles a large number of choices by showing a further pop-up menu for each character position at which there are multiple matching choices.
object-editor must be an object-editor.
Function, cg package
Arguments: widget new-value old-value
This symbol is exported only because it is included in code that is generated into the .bil file of an object-editor form window in a project. It should not be used directly by applications.
Generic Function, cg package
Arguments: object &optional package
Returns a Lisp form derived from an arbitrary object. When a command that acts on a Lisp form (such as macroexpand) is invoked in the Allegro development environment, the default selected-form method finds a Lisp form to apply the command to by calling object-form on the selected-object of the selected window. Object-form may return nil if a Lisp form cannot be derived in some reasonable way from the object. Object-form is bypassed if there is a more specific selected-form method for a particular command and selected window; these more specific methods sometimes exist when it is not sufficient to funnel through the general selected-object in order to derive a selected-form for the window.
Generic Function, cg package
Arguments: object
Returns the locale that is used when printing text to a window or widget, and when reading the value out of a text-editing widget. This may affect which character set is used for non-ASCII character codes.
The setf of this function may be used to set the locale of an object. The value may be either nil (to use the global locale) or a locale object (see device-open). The default is nil.
Methods are supplied for cg-stream (for windows, menus, bitmap-streams, and printer streams) and for dialog-item (for all widgets). For widgets supplied by the underlying windowing system, the locale will have an effect only if the particular widget supports setting its locale. In Windows, locales appear to be supported by all widgets that display text except for single-item-list, multi-item-list, button, static-text, and combo-box (though they do work in the typable pane of a typable combo-box).
See also with-object-locale.
Generic Function, cg package
Arguments: object
Returns a string derived from an arbitrary object. When a command that acts on a string (such as apropos or find-in-files) is invoked in the Allegro development environment, the default selected-string method finds a string to apply the command to by calling object-string on the selected-object of the selected window. Object-string may return nil if a string cannot be derived in some reasonable way from the object. Object-string is bypassed if there is a more specific selected-string method for a particular command and selected window; these more specific methods sometimes exist when it is not sufficient to funnel through the general selected-object in order to derive a selected-string for the window.
Generic Function, cg package
Arguments: object &optional package
Returns a symbol derived from an arbitrary object. When a command that acts on a symbol (such as trace or quick-symbol-info) is invoked in the Allegro development environment, the default selected-symbol method finds a symbol to apply the command to by calling object-symbol on the selected-object of the selected window. Object-symbol may return nil if a symbol cannot be derived in some reasonable way from the object. Object-symbol is bypassed if there is a more specific selected-symbol method for a particular command and selected window; these more specific methods sometimes exist when it is not sufficient to funnel through the general selected-object in order to derive a selected-symbol for the window.
Generic Function, cg package
Arguments: ocx-widget-window
Applies to the Windows platform only.
Returns an integer that is the handle to the OCX control that has been placed into an ocx-widget-window, where the ocx-widget-window is the "site window" for the OCX control. (The function handle returns the handle of the site window.) These handles may be useful if you need to use lower-level OLE functionality on the control.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the color of the argument lamp when it is off. The value should be a RGB color object (see make-rgb) or nil.
If the value is nil, the effective off-color will be computed automatically from the on-color and the off-color-factor properties, by multiplying the red, green, and blue components of the on-color by the off-color-factor number. This allows changing the overall color of the lamp periodically by changing only the on-color, letting the off-color match it automatically.
When an RGB color, that color is used directly. The default value is nil.
When the value property of lamp is a two-dimensional array (so an array of lamps is displayed), the value of this property may also be an array of the same dimensions, with values colors (or nil), allowing each lamp to have its own off-color.
See the description of the lamp control.
Generic Function, cg package
Arguments: lamp
The value should be a real number between zero and one, inclusive. When the off-color property is nil, an effective off-color is computed by multiplying the red, green, and blue components of the on-color by this number. The default value is 0.5.
For example, suppose:
off-color is nil
off-color-factor has its initial value of 0.5
Then the color displayed when the lamp is off is a medium gray (the result of (make-rgb :red 127 :blue 127 :green 127)).
See the description of the lamp control.
Generic Function, cg package
Arguments: configuration
The default default-top-left method uses this configuration option to determine the positioning of a new window when make-window is called with no argument that explicitly indicates a position for the new window.
If true (the default), then a new window is created by default with its top-left corner near the top-left corner of the window that is currently selected on the owner window (or screen) of the new window. If there is no such selected window, then the upper left corner of the owner window (or screen) is used.
If nil, then a new window is created by default with its top-left corner near the position that was most recently used as a default position for a new window (even if that window has since been moved from that position or is no longer selected). If no default window position has been used yet, then the upper left corner of the owner window (or screen) is used.
The term "near" in both cases above means shifted rightward and downward by the height of a window title-bar (see title-bar-height) plus a resizing border. This means that a sequence of windows created with default positioning will initially be positioned so that all of their title-bars are visible simultaneously.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-change event property of dialog-item. The value of the on-change property should be a function (function object or function name, such as a symbol) to be called when the dialog-item's value is changed. The application supplies this function to implement any side effects that should be done when the value changes. The on-change function will be called regardless of whether the value was changed interactively (by the user clicking on or typing into the component) or programmatically (via a call to (setf value)). The on-change function will not be called if the value is changed by calling initialize-value.
The value of on-change may be nil if no function needs to be called.
The function should take three arguments, which are (1) the control (i.e. dialog-item), (2) the new value of the control, and (3) the old (previous) value of the control.
The function should return true if the application accepts the new value. If it returns nil, then the previous value will automatically be restored to the control.
The function may also return a true second value to indicate that if the parent window is currently being invoked as a modal dialog, then the dialog should now exit, returning this dialog-item from the call to pop-up-modal-dialog that invoked the dialog.
The on-change function will only be called if the new value is different from the old value. The value of the on-change-test event property is a function which takes the old and new values as arguments and returns nil if they are different (and the on-change function should be called) and true if they are the same (and on-change should not be called).
on-change is distinct from on-click. For example, if the user clicks an item-list control on the value that is already selected, then the on-click function will be called but not the on-change function (assuming that the on-change-test function returns true, which it will if it has the default value widget-value-equal). On the other hand, if the value of a control is changed programmatically by application code, then the on-change function will be called but not the on-click function. For a button widget in particular, the value is arbitrarily toggled between t and nil when the button widget is successfully pressed, to cause the on-change function to be called.
If you would like to supply code that runs whenever the value changes in any instance of some widget class, you could add a widget-set-value:after method.
For editable-text and multi-line-editable-text controls with the delayed property turned on (as it is by default for those controls), you should not move the keyboard focus from the parent dialog in an on-change handler, such as by calling select-window or pop-up-modal-dialog. The reason is that the on-change handler may be getting called due to the user clicking down on another widget, where the operating system may be waiting on the mouse button to be released, but the parent dialog will not receive the message for the mouse button release if the keyboard focus has been moved elsewhere.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-change-test event property of dialog-item. The value of the on-change-test property should be a function object or a function name (a symbol naming a function), or nil. This function is called to determine whether an apparent change in the value of dialog-item should trigger a call to the on-change function. If no function is supplied (that is, on-change-test is nil), then no values are ever considered equivalent. (That can be useful for ensuring that the on-change function is always called, even when the value is set to its current value. See the note about eq value below.)
The function (if any) should take two arguments, the old value and the new value.
The function should return nil if the values are different (returning nil is the definition of the values being different) and return true if the values are the same.
The initial value (for all widgets) is the function name widget-value-equal. When the two values being compared are both strings, then this function returns the result of calling string= on the two values; otherwise the result of calling eql on the values is returned. This special function is provided in order to match string values properly (so strings with identical characters will be considered the same), but without inefficiently recursing into deep trees or other complex widget values needlessly, as equal (which does consider strings with identical characters the same) might do.
The on-change-test is also used internally to find values in some kinds of controls. For example, when the value of an item-list control is set, the range of values is searched for the new value, using the on-change-test to test which range value is equivalent to the new value so that it may be selected.
See cg-events.html for information about event handling in Common Graphics.
Suppose the value of a widget has contents subject to modification, such as a list. If you modify the elements of the list but do not create a new list, the old and new value will be eq and the default on-change-test function will see the old and new value as the same, behavior which you presumably do not want. In that case, nil is the appropriate value for the on-change-test: some efficiency is lost because the widget is always updated but no intended change is missed.
Generic Function, cg package
Arguments: list-view
This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.
Returns the value of the on-check property of a list-view control. The value may be set at creation time by passing the :on-check initarg to make-instance, or any time later by calling (setf on-check).
The value of this event-handler property should be a function or the name of a function or nil. The default is nil. When the value is a function or function name and the show-check-boxes property of the list-view is true, then the function will be called whenever the state of one of the list-view's check boxes has changed. This includes when the user interactively toggles a check box by clicking on it, as well as when the application programmatically changes the state of a check-box by calling (setf checked). The function should accept three arguments, which will be the list-view widget, the list-view-item that was modified, and t or nil to indicate whether the item was checked or unchecked respectively.
Generic Function, cg package
Arguments: dialog-item-or-menu
Returns (or sets with setf) the value of the on-click event property of dialog-item-or-menu.
For dialog items, the value of the on-click property should be a function object or a function name (a symbol naming a function). This function is called when the left mouse button is clicked down while the mouse cursor is over the dialog-item. This function should accept two arguments, the dialog holding dialog-item and dialog-item itself. The value may be nil if no function needs to be run.
on-click is distinct from on-change. For example, if the user clicks an item-list control (a single-item-list control, for example) on the value that is already selected, then the on-click function will be called but not the on-change function (assuming on-change-test has its default value eql). On the other hand, if the value of a control is changed programmatically by application code, then the on-change function will be called but not the on-click function.
It is usually more appropriate to use an on-change function rather than an on-click function, even for a button widget. If the user presses a button widget by pressing the spacebar when the button widget has the keyboard focus, then the on-change function is called but the on-click function is not called. And if the user clicks the mouse button down over a button widget but then drags off of the widget before releasing the mouse button (to abort pressing the button widget), then the on-click function is called but the on-change function is not. Successfully pressing a button widget arbitrarily toggles the widget's value between t and nil to cause the on-change function to be called.
Note that the on-click function of a Windows tab-control will be called only when clicking on its tabs, not when clicking in the tab-control body.
The on-click event handler is also defined for menus, where it works differently than on dialog-items. It is called by the default handle-menu-selection method, and should take the three required arguments menu, menu-item, and stream.
The menu argument is the menu that contains the chosen menu-item. The menu-item argument is the menu-item that was chosen. The stream argument is either the window on which the menu was invoked with pop-up-menu, or else the window on which the menu was defined. If the menu was invoked by calling pop-up-menu, then any values returned by the on-click handler will then be returned from the call to pop-up-menu.
The default on-click handler for menus is default-menu-on-click, which simply returns the value of the chosen menu-item. This default handler may be used when using pop-up-menu to invoke the menu, where the code that called pop-up-menu then proceeds to process the returned value in some way. A menu on a menu-bar, on the other hand, needs to use some other on-click handler that processes the chosen menu-item itself in some way before returning, since menus on menu-bars do not return anything to the application. A few standard alternate on-click handlers for menus are supplied by Common Graphics; these are:
Any given menu may use one of these built-in choices if appropriate, or else use a custom on-click handler.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the color of the argument lamp when it is on. The value may be an RGB color object, as created with make-rgb, or else nil to default to green. The default value is the value of the symbol green.
When the value property of lamp is a two-dimensional array (so an array of lamps is displayed), the value of this property may also be an array of the same dimensions, with values colors (or nil), allowing each lamp to have its own on-color.
See the description of the lamp control.
Generic Function, cg package
Arguments: html-widget
Returns a function that will be called by the default html-widget-command-change method, or else nil if no function has been supplied.
You can call (setf on-command-change) to set the function to be called. The function should take three arguments, which are the same arguments that were passed to html-widget-command-change.
See the html-widget control.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-double-click event property of dialog-item. The value of the on-double-click property should be a function object or a function name (a symbol naming a function). This function is called when the left mouse button is double-clicked while the mouse cursor is over dialog-item. This function should accept two arguments, the dialog holding dialog-item and dialog-item itself. The value may be nil if no function need be run.
The value may also be the special keyword :push-again. This value causes the second click of a double-click to call the on-change function of the control, if any. Since the first click of a double-click always calls the on-change function (if any), this special value means that every click of a rapid series of clicks will call the on-change function. By contrast, when on-double-click is nil, nothing is done on the second click of a double-click. This default behavior prevents the user from accidentally calling the on-change function twice on an accidental double-click, and so :push-again must be specified explicitly when rapid-fire clicking to invoke the on-change function for every click is desired instead. (A small limitation of :push-again is that the control will not visibly depress a second time for the second click of a double-click, despite the name.)
Consider a use of on-change to change the value displayed in a static text widget. If only two values are possible, suppressing an immediate second click (as is done when on-double-click is nil) may be useful as the second click is probably unintended. But if on-change cycles through a longer list of values, rapid multiple clicks are likely intentional and the :push-again for on-double-click would be appropriate.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: split-bar
Returns the on-drag property of a split-bar widget. The value may be set at creation time by passing the :on-drag initarg to make-instance, or any time later by call (setf on-drag).
The value of this property should be the name of a function that will be called repeatedly as the user drags the split-bar interactively, or else nil to not call an on-drag function at all. The default value is nil. You may use setf to set the value of this property.
Typically it is more convenient to use the min-space-before and min-space-after properties to constrain split-bar movement, when that is adequate.
When the value is a function, it will be called once each time the system notices that the split-bar has moved to a new position during a drag. The function should accept two arguments, which will be the split-bar widget and an integer indicating the new position. The function should return an integer indicating the position to which the split-bar should be constrained. The return value should therefore be the value argument itself whenever there is no need to constrain the movement. An on-drag function may also perform arbitrary side effects before returning the constrained position integer.
The position integer argument works like the value property of the split-bar, indicating the distance in pixels from the top of the parent window's interior to the split-bar when it is horizontal, or the distance from the left side of the parent window's interior to a vertical split-bar.
The widgets in the widgets-to-move and widgets-to-resize properties will still be moved and resized as usual when there is an on-drag function, though they will be moved and resized according the new split-bar position as it was constrained by the on-drag function as well as by the min-space-before and min-space-after properties.
Generic Function, cg package
Arguments: dialog-item
This widget property may be either nil or a function name symbol. When a function name, the function will be called, for application side effects, just after drag-and-drop does a drop on the widget. The function will be passed five arguments, which are:
The dropped-on widget (this is the widget that has the on-drop function)
The dragged-from widget
The value that was dropped
The position within the widget where the user released the mouse button to do the drop (a Common Graphics position object, see About the position class).
The move-values argument that was passed to drag-and-drop.
Generic Function, cg package
Arguments: rich-edit
Returns (or sets with setf) the value of the on-format-change event property of rich-edit, which should be an instance of the rich-edit control class. The value should be a function object or a function name (a symbol naming a function). This function is called whenever a formating change is made to the rich-edit control. The value can also be nil, in which case no function is called.
The function should take three arguments: (1) widget --- the rich-edit control, (2) type --- either the symbol :character or the symbol :paragraph, indicating which type of format change occurred, and (3) args --- the list of keyword arguments that were passed either to set-character-format or set-paragraph-format
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-kill-focus event property of dialog-item. The value of the on-kill-focus property should be a function object or a function name (a symbol naming a function). This function is called by the default kill-focus-event method when keyboard focus leaves dialog-item. This function should accept one argument, the dialog-item. The value may be nil if no function need be run.
See also on-set-focus.
In general, do not move the keyboard focus from the parent dialog in an on-kill-focus handler, such as by calling select-window or pop-up-modal-dialog. The reason is that the on-kill-focus handler may be getting called due to the user clicking down on another widget, where the operating system may be waiting on the mouse button to be released, but the parent dialog will not receive the message for the mouse button release if the keyboard focus has been moved elsewhere.
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: position end1 end2 &key (margin 4)
Returns true if position is on the line segment that extends from end1 to end2, within a margin of error specified by the margin keyword argument, and otherwise returns nil. position, end1, and end2 must all be position objects (see make-position).
The margin keyword argument must be a non-negative real number, and is typically a small positive value to allow the user to click on a line that is drawn in a window without having to click precisely on the line. The default value of 4 allows the user to miss the line by up to 4 pixels on either side; then if a call to this function with the clicked position and the endpoints of the drawn line returns true, then an application can decide that the user clicked on the line and take appropriate action. When the line is more nearly horizontal than vertical, this margin is measured vertically from the line, and otherwise it is measured horizontally from the line.
An error is signaled if end1 and end2 are position= to each other.
See also on-line-segment-x-y-p.
function, cg package
Arguments: *x y end1-x end1-y end2-x end2-y &key (margin 4)
Returns true if a point lies on (or nearly on) a line segment amd returns nil otherwise.
The first two arguments are real numbers for the X and Y coordinates of the point, and the remaining required arguments are real numbers for the endpoints of the line segment.
The margin argument is a real number indicating the distance from the line within which the point must lie to be considered on the line. If it is within this distance, then true is returned, and otherwise nil is returned.
See also on-line-segment-p.
Generic Function, cg package
Arguments: html-widget
Returns a function that will be called by the default html-widget-over-link method when the mouse cursor moves onto or off of a link. Returns nil if no function has been supplied.
You can call (setf on-link-message) to set the function to be called. The function should take two arguments, which are the same arguments that were passed to html-widget-over-link.
An on-link-message function will not be called on Windows, where Common Graphics does not know when the mouse cursor has moved onto a link.
See the html-widget control.
Generic Function, cg package
Arguments: list-widget
If this event handler property of an item-list, list-view, or outline widget is a function name or function object (rather than its default value of nil), then the default list-item-mouse-in or outline-item-mouse-in method will call that function whenever the mouse cursor moves over an item in the list. This can be used for side effects such as displaying help messages.
The function should take three arguments, which are the widget, the index of the item in its range, and the item itself. The item for an item-list is the actual value that's displayed; for a list-view it is a list-view-item object; and for an outline it is an outline-item object.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-mouse-in event handler for the argument control. The value of the on-mouse-in property should be a function object or a function name (a symbol naming a function). This function is called when the mouse cursor is moved into the control's rectangular area. on-mouse-in may be nil if no function need be run.
If an on-mouse-in function is supplied, it should take three arguments, which are (1) the control, (2) the mouse-button-state at the time the mouse moved into the control, and (3) the window that the mouse was most recently in. The return value does not matter.
Many functions take a mouse-button-state argument. This argument is a single integer that tells what combination of mouse buttons and shift keys when the message that is being handled occurred. Each mouse button or shift key is represented by a constant that has a single bit flagged, and so bit tests on the button-state argument can be used to tell whether particular mouse buttons or shift keys were down. The particular constants are left-mouse-button, middle-mouse-button, right-mouse-button, first-x-button (see *ignore-mouse-x-buttons*), second-x-button (see *ignore-mouse-x-buttons*), shift-key, control-key, and alt-key.
See also on-mouse-out.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-mouse-out event handler for the argument control. The value of the on-mouse-out property should be a function object or a function name (a symbol naming a function). This function is called when the mouse cursor is moved out of the control's rectangular area. on-mouse-out may be nil if no function need be run.
If an on-mouse-out function is supplied, it should take three arguments, which are (1) the control and (2) the mouse-button-state at the time the mouse moved into the control, and (3) the window that the mouse moved into from this control. The return value does not matter.
Many functions take a mouse-button-state argument. This argument is a single integer that tells what combination of mouse buttons and shift keys when the message that is being handled occurred. Each mouse button or shift key is represented by a constant that has a single bit flagged, and so bit tests on the button-state argument can be used to tell whether particular mouse buttons or shift keys were down. The particular constants are left-mouse-button, middle-mouse-button, right-mouse-button, first-x-button (see *ignore-mouse-x-buttons*), second-x-button (see *ignore-mouse-x-buttons*), shift-key, control-key, and alt-key.
See also on-mouse-in.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: html-widget
Returns a function that will be called by the default html-widget-new-document method when the html-widget has finished loading a page, or else nil if no function has been supplied.
You can call (setf on-new-document) to set the function to be called. The function should take two arguments, which are the same arguments that were passed to html-widget-new-document.
See the html-widget control.
Generic Function, cg package
Arguments: html-widget
Returns a function that will be called by the default html-widget-new-window method when a link wants to make a new browser, or else nil if no function has been supplied.
You can call (setf on-new-window) to set the function to be called. The function should take one argument, which is the html-widget.
See the html-widget control.
Generic Function, cg package
Arguments: dialog-item
This widget (specified by the dialog-item argument) property may be either nil or a function name symbol. When a function name, the function will be called, for application side effects, just after paste-selection pastes something in the widget. (Often a menu command will call paste-command directly, which calls paste-selection.)
The function will be passed two arguments, which are (1) the widget and (2) the value that was pasted.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-print event property of dialog-item.
The value of the on-print property should be a function object or a function name (a symbol naming a function), or nil. nil means use princ-to-string.
The function which is the value of this property is called whenever the dialog-item's value is being formatted for display in the dialog-item. It is also called for each member of the dialog-item's range when the range is a list of possible values that are shown in the control. The function should accept one argument, which is the value itself, and should return a string to display in the dialog-item for that value. The default differs for various dialog-item classes, but is usually a standard print function such as princ-to-string.
Using an on-print function allows the value of a dialog-item to be a meaningful Lisp object while the visible control itself displays an arbitrary nicely-formatted string to represent it. This is particularly useful in controls that display a set of choices: when the user selects a value, there is no need to map from the selected string to a meaningful Lisp object, since that Lisp object will be the control's value.
Most dialog-items that can display strings implement on-print. In addition, a list-view-column object may be given an on-print function to format the values in a single column of a list-view control differently than other columns of the same control. And a combo-box-column-mixin grid-column may be a given an on-print function to format the values in its drop-down list of choices (though the value displayed in the actual cell is formatted by the column's data-read-converter).
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the on-print-chart-object property of a chart-legend. The value may be set at creation time by passing the on-print-chart-object initarg, or any time later by calling (setf on-print-chart-object).
A function that returns a label for a chart object in the chart-legend of a chart-or-plot.
The value of this property should be a function or a function name, or else nil to default to princ-to-string. The function should take a chart object ID as a single argument and return a string to display for that object. The default value is princ-to-string.
A chart object ID will be the :id value for the object in the chart-objects property of the chart-or-plot, if such a value has been supplied, and otherwise will default to the zero-based integer index of the object.
This property is used only when the draw-legend property of the chart-or-plot is true.
See also legend-font, layout-orientation and on-print-major-label.
An alternative to writing an on-print-chart-object function is to supply an explicit :label value for each object in the chart-objects property of the chart-or-plot.
See chart-widget, plot-widget, and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the on-print-major-label property of a chart-axis. The value may be set at creation time by passing the on-print-major-label initarg, or any time later by calling (setf on-print-major-label).
A function that returns a label for a major tic position of a chart-axis in a chart-widget.
The value of this property should be a function or a function name, or else nil to default to princ-to-string. The function should take a chart value as a single argument and return a string to display for that value. The default value is princ-to-string.
For a value-axis, the argument to the function will be a real number between the range-bottom and range-top of the axis (inclusive).
For an item-axis, the argument will be a chart item ID. A chart item ID may be any arbitrary value that has been passed as the item-id argument to set-chart-value or returned from a chart-value-returner function when its value-type argument is :id. If no such explicit ID has been provided for a particular chart item, then the chart item ID defaults to the zero-based integer index of the chart item.
The returned string may contain embedded newline characters to wrap labels onto multiple lines. The widget will leave enough space for the multiple lines of text. For an item-axis, the printed string will be wrapped at all spaces automatically if the major-label-wrapping property is true.
This property is used only when the draw-major-labels property of the chart-axis is true. See also major-label-frequency, on-print-minor-label, and on-print-chart-object.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the on-print-minor-label property of a chart-axis. The value may be set at creation time by passing the on-print-minor-label initarg, or any time later by calling (setf on-print-minor-label).
A function that returns a label for a minor tic position of a chart-axis in a chart-widget. The default value is princ-to-string.
This property works just like on-print-major-label except for minor tic positions rather than major ones. See on-print-major-label for details.
This property is used only when the draw-minor-labels property of the chart-axis is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: html-widget
Returns a function that will be called by the default html-widget-progress method while the html-widget is loading a web page or file, or else nil if no function has been supplied.
You can call (setf on-progress) to set the function to be called. The function should take three arguments, which are the same arguments that were passed to html-widget-progress.
See the html-widget control.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-range-change event property of dialog-item. The value of the on-range-change property should be a function object or a function name (a symbol naming a function). This function is called when the range of dialog-item is changed. This function should accept three arguments, the dialog-item, the new range, and the old range. The value may be nil if no function need be called. (The function is not responsible for changing the range. It just provides a way for the application to do whatever it wishes when the range is changed.)
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: drawable-or-split-bar
Returns (or sets with setf) the value of the on-redisplay event property of the argument. The value should be a function object or a function name (a symbol naming a function). This function will be called by the default redisplay-event method whenever a drawable needs to be redrawn, such as when it is uncovered. Note that if the default redisplay-event method is overridden, then the on-redisplay will not be called by it. If the value of the on-redisplay property is nil, then no function is called.
The on-redisplay function should take two arguments, (1) the drawable control and (2) the stream to draw on. If the use-bitmap-stream property of the control is true, then the stream argument will be the bitmap-stream of the control; otherwise it will be the visible window of the control. The on-redisplay function should draw whatever it draws on the stream object; if this is a bitmap-stream, then the drawable will automatically quickly copy what was drawn there to the visible window.
Here is the sample on-redisplay function that is used initially by a drawable control when it is interactively instantiated onto a form in the IDE. This should of course be replaced by some other function more appropriate to the application. Note that it draws its drawing to fit the current page size of the drawable.
(defun on-redisplay-example (drawable stream)
(declare (ignore drawable))
(let* ((width (page-width stream))
(height (page-height stream))
(mid (floor width 2))
(num-lines 24)
(factor (float (/ width (1- num-lines))))
)
(dotimes (j num-lines)
(draw-line stream
(nmake-position #.(make-position 0 0) mid height)
(nmake-position #.(make-position 0 0)
(round (* j factor)) 0)))))on-redisplay is a property of the drawable class.
Returns the on-redisplay property of a split-bar widget. The value may be set at creation time by passing the :on-redisplay initarg to make-instance, or any time later by call (setf on-redisplay).
The value of this property should be the name of a function that will be called when needed to draw the split-bar, or else nil to draw the split-bar in the default way. The default value is nil. You may use setf to set the value of this property.
When nil, the split-bar is drawn as a simple colored line according to the color-when-idle, color-under-mouse, or color-when-dragging property.
When a function, the function should accept two arguments, which will be the split-bar dialog-item itself and the associated split-bar-pane widget-window. Drawing functions should be called on the split-bar-pane to draw the widget. The function would typically draw somewhat differently depending on whether the now-dragging and now-under-mouse properties of the split-bar are true.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the on-set-focus event property of dialog-item. The value of the on-set-focus property should be a function object or a function name (a symbol naming a function). This function is called by the default set-focus-event method when the keyboard focus moves to dialog-item. This function should accept one argument, the dialog-item. The value may be nil if no function need be called.
See also on-kill-focus.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: list-view-column
Returns or sets with setf the value of the on-sort-key event property of list-view-column. See list-view and list-view-column.
The value should be a function object or a function name (a symbol naming a function), or nil. The function should accept one argument and is applied to each object in list-view-column to be sorted to produce the actual value on which sorting is based. See the key argument to sort. If the value is nil, the objects themselves are sorted.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the on-sort-predicate event-handler property of a dialog-item.
The value may be a function name or function object, which determines the ordering of items in a list-view-column, grid-column, outline, or item-list control. The value may also be nil to indicate that the control is not sortable (using its built-in sorting functionality), except that a grid-widget will default to using default-grid-sorter. When the value is a function, the function should accept two arguments and return true when the first value should precede the second (as with the predicate argument to sort.
For a list-view-column, where the sorted values are always strings, the default value is string-lessp (for a case-insensitive alphanumeric sort). For an outline, the default is nil because the sortable values are arbitrary Lisp objects, and so there is no possible general default predicate that would not cons strings in many cases. For an outline a custom on-sort-predicate must be supplied in order to use the built-in sorting behavior. For an item-list the default value is nil, which causes all types of values to be sorted alphanumerically, though some types of values other than strings and symbols would create strings to sort by.
The on-sort-predicate function (if any) is used when calling sort-grid on a grid-widget, when calling add-outline-item-value (without an explicit position argument) or replace-outline-item-value on an outline control, when calling list-view-sort, (setf sort-column) or (setf sort-reverse) on a list-view control (which happens internally when clicking a list-view column header).
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: timer
This function returns the value of the on-timer event property of the argument timer. The value should be a function object or a function name (a symbol naming a function). The function is invoked after timer's interval has elapsed (assuming that the default timer method has not been overridden). The function should take a single argument, which is the timer itself. Its returned values are not used. The default value is nil, and so a timer will not do anything when its interval has elapsed unless it is given a custom on-timer function (or a timer method is added for it).
An on-timer function can be specified with the :on-timer initarg when creating a timer instance with make-instance and setf can be used with on-timer to set or change the on-timer function of a timer.
See cg-timers.html for more information on timers. See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: items device stream &rest options &key pop-up
This function is obsolete. You should create dialogs with make-window with dialog (or some subclass of dialog) as the device argument. open-dialog exists for backward compatibility only.
open-dialog creates and returns a dialog. The arguments are interpreted as follows.
items is a list of dialog item structures.
device is a symbol specifying the device manager for the dialog. The manager dialog is usually available, but other devices may be appropriate to your machine.
stream: must be a background stream or a window.
If stream is a background stream, the dialog is created to be displayed on it. If it is opened in pop-up mode, then its position will be "culturally compatible" with the host machine unless overridden by one of the options.
options are pairs of keys and values, treated the same as for open-stream. In particular, :font may be used to set the default font for dialog items. The options supported depend on the device manager.
pop-up: if true, the dialog is opened in pop-up mode with state as :shrunk, otherwise it is opened in continuous mode with state as :normal.
Generic Function, cg package
Arguments: image-list
This function opens the argument image-list so that it may be used. Currently Common Graphics uses image-lists only for list-view controls, which automatically open their image-lists when needed, so this function is not likely to be needed by applications. See also image-list-open-p.
See list-view.
Function, cg package
Arguments: widget-window options
This function is supplied for developers who write their own widgets from scratch in Lisp. It should be called in a device-open method for the widget to create the actual operating system window for the common graphics window object. The examples for the vertical gauge and the circle widget on the Examples tab of the Navigator dialog demonstrate use of this function.
Function, cg package
Arguments: items class stream &rest options &key add-to-menu pop-up help-string
Creates and returns a menu, or returns nil if the request to the Operating System to create a new menu fails (see the information under the heading open-menu returns nil if a menu cannot be created near the bottom of this page) or if the class and stream arguments are inconsistent. If a menu is created, open-menu returns two values. The first is always the new menu. The second depends on stream. The arguments are interpreted as follows:
items is a list of elements which can be a mixture of types menu-item, cons or atom. Each element is coerced in the following way:
element is a menu-item: it is used.
element is a cons: a menu-item is created with a form like (make-instance 'menu-item :name (car element) :value (cdr element)).
element is an atom: a menu-item is created with a form like (make-instance 'menu-item :name element).
For each menu-item specifier in the items list that is not an actual menu-item, the string to appear on the menu for the item is created automatically by capitalizing the print name of the menu-item name and replacing any dashes with spaces. If this built-in formating is not suitable, then always pass actual menu-items whose title properties are the appropriate strings.
To insert a horizontal line between groups of menu-items, include a menu-item whose title is a string containing only a single dash character ("-"). Other attributes of the menu-item will be ignored for this special case. Alternately, include the value of the variable menu-separator in the list of menu-items instead of an actual menu-item.
Note that a specific menu-item can only be placed on one menu at a time. If you want identical menu-items on two menus, create two separate but identical menu items. You can copy a menu-item with copy-menu-item.
The class argument is the name of the menu class to instantiate. It should be either pop-up-menu, pull-down-menu, or menu-bar, or a subclass of one of those classes. (An application may define its own menu subclasses in order to add methods to standard menu generic functions.) Note that pull-down-menu is already a subclass of pop-up-menu.
The stream argument is the parent on which to create the menu, and must match the specified class. If class is pop-up-menu or one of its subclasses (but not pull-down-menu or one of its subclasses), and stream is an existing pop-up-menu (or pull-down-menu), then the new menu will be created as a submenu of the pop-up-menu. If class is a pull-down-menu or one of its subclasses, and stream is an existing menu-bar, then the new menu will be created as a pull-down menu of the menu-bar. If class is a menu-bar, and stream is a top-level window that has a title-bar, then the new menu will be created as the menu-bar of that window.
In addition to the above combinations, stream may be (screen *system*) (see screen and *system*), regardless of the value of class, in order to create a menu without yet putting it on a specific parent or displaying it. A pop-up-menu created on the screen may be invoked later as a top-level pop-up-menu by calling the function pop-up-menu. A pop-up-menu or pull-down-menu created on the screen may be added later to a pop-up-menu or menu-bar parent (respectively) by calling add-to-menu. A menu-bar created on the screen may be added later to a window by calling (setf menu) or by passing it as a menu keyword argument to make-window.
The pop-up argument specifies whether a pop-up-menu rather than a menu-bar is being created. The default value is t, so if class is menu-bar or one of its subclasses, then pop-up should be passed explicitly as nil.
If the class and stream arguments do not match as described above, then nil is returned. (To recap, stream can always be (screen *system*) regardless of the value of class. If stream is not (screen *system*), then if class is pop-up-menu or one of its subclasses (but not pull-down-menu or one of its subclasses), stream must be an existing pop-up-menu or pull-down-menu. If class is a pull-down-menu or one of its subclasses, and stream must be existing menu-bar. If class is a menu-bar, stream must be a top-level window that has a title-bar.)
Otherwise two values are returned: (1) the menu that was created, and (2) the menu-item that was created in order to add the new menu to a parent menu, if one in fact was created, and nil otherwise. A menu-item is created only if class is pop-up-menu or one of its subclasses, stream is a menu, and the add-to-menu argument is true.
help-string is used only if the stream argument is a menu. In that case, the new menu being created by this call to open-menu becomes a child menu of the parent menu specified by the stream argument, and a new menu-item is automatically created and added to the parent menu for invoking the new child menu. help-string will become the help-string of this new menu-item on the parent menu. A menu-item-highlighted method for the parent menu may make use of this help-string, such as by calling window-message or status-bar-message to display the help-string in a status-bar whenever the end user highlights the menu-item. This works even when the parent menu is a menu-bar (in which case the new menu-item is displayed on the menu-bar itself to invoke a pull-down menu).
options are pairs of keys and values, treated the same as for make-window. Any make-window initargs that may work for menus but are not explicit keyword arguments to open-menu may thus still be specified. Options include:
title: this argument is used only if the stream argument is a menu. In that case, the new menu being created by this call to open-menu becomes a child menu of the parent menu specified by the stream argument, and a new menu-item is automatically created and added to the parent menu for invoking the new child menu. title will be used as the label of this new menu-item on the parent menu. If the parent menu is a menu-bar, then the title will be displayed on the menu-bar itself. Note that the Windows operating system does not support titles on non-child pop-up menus.
on-click: the value of this argument should be a function name or function object naming the function that is called whenever a menu-item is selected. Such a function is passed three arguments: the menu, the menu-item chosen and the owning stream (e.g. (screen *system*) -- see screen and *system* -- for pop-up menus, or some other menu bar for pull-down menus). The default on-click function simply returns the unevaluated value of the selected menu-item, but eval-menu-item, funcall-menu-item, and funcall-menu-item-with-window may be useful.
Pop-up menus are displayed by calling pop-up-menu. The value returned by the on-click is also returned by pop-up-menu so your code can use that value to decide what action to take. Pull-down menus, however, are displayed by an internal function whose return value is not available to user code. So, for pull-down menus, the on-click is quite important: if it does not do anything, choosing a menu-item from a menu will not do anything. The default function, which, as said above, simply returns the unevaluated value of the selected menu-item, does not do anything useful for pull-down menus since the returned value is discarded by the (internal) function that displayed the menu. Again, the functions eval-menu-item, funcall-menu-item, and funcall-menu-item-with-window are useful for pull-down menus.
add-to-menu controls the effect of creating a menu when the stream argument to open-menu is an existing menu. In that case, the argument should be one of the following values (the same values that the position argument to add-to-menu can have):
:start: add new menu at the start of stream menu
:end: add new menu at the end of stream menu
non-negative integer: the menu-item that is created for the new menu is inserted into the parent menu (the value of the stream argument) at that index position, as in add-to-menu. (Position zero is the start of the menu. An integer position greater than the length of the menu is interpreted as the end of the menu.)
The new menu is incorporated into a menu-item whose name is the title of the new menu and whose value is the new menu. In this case, the second value returned from open-menu is the new menu-item added to stream menu.
While it is typical not to specify a value when stream is not a menu, you can specify nil in that case.
open-menu returns nil if the operating system failed to make the requested menu. Such failure is typically due to one of the operating system's tables for all windows and menus becoming full. This situation should be rare, but if it does happen then your application should be modified to close any windows or menus that are no longer being used, in order to free up the corresponding operating system resources. Note that removing a menu-bar from a window (by passing nil to (setf menu)) does not close the menu, and closing a menu does not close its sub-menus, since each of these can still be used elsewhere. If your application creates lots of menus over time, it is prudent to call close on each menu and sub-menu that will no longer be used.
See also the menu chapter in the IDE User Guide, which has examples using this function. See also the Menu Editor.
Generic Function, cg package
Arguments: outline item-value &optional no-redisplay-p
Causes the subitems of the outline-item of outline whose value is item-value to be displayed. The redisplay is delayed if the optional argument is specified true.
Alternately, (setf state) may be called to change the state of an outline-item. This may by more efficient if you have the outline-item object in hand, rather than its value only. See the description under the heading State on outline-items near the bottom of the page for state.
Generic Function, cg package
Arguments: stream rgb-vector &optional animated-entries
This and other palette functions should be called only when running in Windows desktop mode. And palettes are essentially obsolete there as well, now that machines generally always run in true-color mode. But the palette API still exists for Windows desktop mode.
Creates and returns a palette and returns a handle to that palette (i.e. an integer) that is appropriate to assign to stream. stream should be a cg-stream. Generally this palette will be compatible with all windows, and (screen *system*) (see screen and *system*) may be used as a value for stream. Palettes should be needed only if Windows is running in 256-color mode or less and the standard VGA colors are not sufficient.
rgb-vector should be a vector of up to 256 rgb colors. For example, the following form returns a vector of six colors using predefined colors (cyan, red, black, and white) and new colors created with make-rgb:
(setq cv (vector cyan (make-rgb :blue 10 :red 33)
red (make-rgb :green 154 :red 0 :blue 99)
black white))animated-entries should be a list of indices of rgb-vector which are candidates for animation. See animate-color-number. The Operating System is instructed not to share these colors.
With cv as defined just above, create a suitable palette for (screen *system*) (see screen and *system*) with
(setq my-palette (open-palette (screen *system*) cv))Note that this function does not assign the returned palette to stream. That must be done with (setf palette).
Efficiency note: When a window is closed or a palette is removed from it by calling (setf palette), Common Graphics does not automatically close the palette to clean up its operating system resources. The reason is that other windows could be using the same palette (now or in the future), so Common Graphics does not know when it is safe to close it. Therefore, if an application creates many palettes, it may need to call close-palette to close each one to prevent the operating system from running out of palette resources. This should be done only when each palette is no longer being used by any window. The resources are cleaned up when Lisp exits.
Warning: the palette handle returned by this function is an address. This address will be valid so long as the current invocation of Lisp is running but may not be valid if the image is dumped (with dumplisp) and rerun (it may be valid if rerun on the same machine, it is less likely to be valid on a different machine running the same operating system, it is very unlikely to be valid on a different machine running a different operating system). Therefore, palettes should be initialized each time Allegro CL (or an Allegro CL application) is run.
For information on when palettes are useful (or necessary) see cg-color-palettes.html.
Generic Function, cg package
Arguments: pixmap &key recreate window
Tells the operating system to create a "device-dependent bitmap" from the texture of the specified Common Graphics pixmap oject (passed as the pixmap argument), and sets the pixmap-handle property of pixmap to be the handle to that device-dependent pixmap. (The pixels and colormap of a device-dependent pixmap are managed in the operating system rather than in Lisp.) If the pixmap has a mask texture (in the mask property), open-pixmap-handle also creates a device-dependent bitmap for the mask texture and stores it in the mask-handle property of the pixmap.
After this is done, whenever the pixmap is drawn the drawing will be accomplished by passing this pixmap handle to the operating system rather than by sending an array of all of the actual pixels plus the pixmap's color palette to the operating system each time. If the pixmap uses a palette that contains colors other than the 20 colors in the default system palette, and the user is running Windows in something less than 24-bit true-color mode (which is now atypical), then the pixmap will be drawn using the correct colors only if (1) the window argument is passed here, (2) that window currently has a palette that contains all of the pixmap's colors, and (3) the pixmap is drawn only in that window without changing that window's palette in the interim.
close-pixmap-handle may be called later to get rid of the device-dependent pixmap if desired, and the pixmap will be drawn thereafter from its Lisp texture once again. open-pixmap-handle does nothing if the pixmap object already has a handle, unless recreate is true, in which case the old pixmap handle will be closed and a new one created. Using a pixmap handle may result in faster drawing, especially of larger pixmaps, but the device-dependent pixmap will also consume operating system pixmap resources.
Function, cg package
Arguments: class-name &optional location direction &rest options
This function creates streams. In Allegro CL for Windows 3.0.x, it was used to create window streams (i.e. windows) as well as other types of Common Graphics streams, such as bitmap-stream and printer streams. Starting in 5.0, however, it should not be used for making windows (although it still works for that purpose for backward compatibility). New code should use make-window instead to make a window.
open-stream should still be used for printer steams and bitmap-streams. The class-name is the class of the stream (either printer, bitmap-stream or an appropriate subclass).
The location and direction arguments are ignored because Common Graphics now uses simple-streams (see Common Graphics and Simple Streams in cgide.html). They remain as optional arguments for backward compatibility. Values must be passed if additional initargs are to be specified, but nil is a suitable value for both arguments.
For example, a printer stream is typically opened with the form
(open-stream 'printer nil nil ...)where the ... may be replaced by any number of initargs. For a list of open-stream initargs for printers, refer to pop-up-printer-job-dialog. Note that if there are no initargs, this will open a printer stream:
(open-stream 'printer)The exact list of possible arguments depends on the class-name.
See also cg-stream.
Generic Function, cg package
Arguments: window
This function is used by the File | Open menu-item of the default menu-bar that may be interactively attached to a form. In the IDE, it demonstrates a typical "Open" command for opening a text file into an editor, but this function is not available in a runtime image. A custom application that implements an "Open" command will need to supply its own code for such a command instead, but it may be useful to model after the default menu-bar's example. Here is the code for the open-text-file example:
(in-package :cg)
(defmethod open-text-file ((window basic-pane))
(let* ((selected-window (selected-window window))
(old-pathname (and selected-window
(file selected-window)))
(pathname
(ask-user-for-existing-pathname "Edit File"
:stream window
;; By default, offer to edit a file from the same
;; directory as the file displayed in the
;; selected window, if it's a text edit window.
:host (and old-pathname
(excl::path-namestring
(pathname old-pathname)))))
editor)
(cond ((null pathname) nil)
((not (probe-file pathname))
#-runtime-system
(ide:lisp-warning "File ~a does not exist." pathname)
nil)
(t
(setq editor
(make-window (gensym-sequential-name :editor)
:title (namestring pathname)
:device 'text-edit-window
:parent window))
(load-file (frame-child editor) pathname)))))See also new-text-editor, save-text-file, and save-as-text-file.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns the pixmap instance used in outline to indicate an outline-item is expanded. opened-pixmap is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns (or sets with setf) the symbol name of the pixmap instance used in outline to indicate an outline-item is expanded. When setting this value, use a pixmap which has been placed in the set of cached pixmaps with cache-pixmap.
opened-pixmap-name is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: outline-pixmap-interface
Returns (or sets with setf) the path namestring of the .bmp pixmap file from which the pixmap instance used in outline to indicate an outline-item is expanded was originally read (if any). When this value is set, load-pixmap is called on the path namestring, a pixmap object is created, and the pixmap is cached with cache-pixmap.
opened-pixmap-source is a property of the outline-item, outline, and dropping-outline classes.
Generic Function, cg package
Arguments: standard-object
Returns the value of the orientation property of the argument. This property applies to trackbar, up-down-control, and split-bar controls that can be placed vertically or horizontally, and to a printer, indicating the orientation of the image on the paper. The possible values for trackbars, up-down-controls, and split-bars are :horizontal and :vertical.
This property is not setfable, excpt for split-bars. For a printer stream, it must be specified as the value of the :orientation initarg to open-stream when creating a printer stream (or by letting the end user specify it on the print job dialog that is invoked by default at that time). For trackbars and up-down-controls, the value must instead be specified with the inspector when designing a control (using a form) or with the :orientation initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
When creating a split-bar programmatically and passing the orientation argument as :vertical, you will probably want to also pass the cursor-name argument as :vertical-splitbar-cursor (or the name of a custom cursor), since it will otherwise default to :horizontal-splitbar-cursor. (This is not an issue when creating a split-bar interactively on a form window.)
The possible values for a printer stream are :portrait and :landscape, where :portrait is taller than it is wide, and :landscape is wider than it is tall.
orientation is a property of the up-down-control, trackbar, split-bar, and printer classes.
Generic Function, cg package
Arguments: top-level-window
This generic function will be called when the operating system is shutting down or logging off the current user. It should return true to allow the shutdown, or nil to cancel the shutdown and leave the Common Graphics application running. The default method returns t (though in the IDE a method returns nil if the ide:query-os-exit configuration option is turned on and the user replies No to an exit confirmation dialog).
A Common Graphics application has no reason to call this function, but it could add a method to it that may decide to return nil to cancel a shutdown.
To disallow exiting an individual Common Graphics application (rather than the entire operating system), see user-close.
function, cg package
Arguments: link node node1-reader node2-reader
This utility function might be useful when using the function graph-layout to draw graphs and handle mouse events on them. See that function for more information.
This function returns the node to which a specified node is connected by a specified link. The link argument should be one of links in the list that would be passed as the links argument to graph-layout. The node argument should be one of the nodes in the list that would be passed as the nodes argument to that function. The node1-reader and node2-reader arguments should be the same as those passed to graph-layout. The node argument should be one of the two nodes of the link argument, which means that either the node1-reader or node2-reader function should return the node argument when passed the link argument. This function will return the node that is returned by the other reader argument.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the outer-border-color property of a chart-or-plot. The value may be set at creation time by passing the :outer-border-color initarg, or any time later by calling (setf outer-border-color).
outer-border-color is the color of a plain border that is drawn just inside the edge of a chart-or-plot if its outer-border-width property is positive. The value should be an RGB object (see make-rgb). The default value is the value of light-gray.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the outer-border-width property of a chart-or-plot. The value may be set at creation time by passing the :outer-border-width initarg, or any time later by calling (setf outer-border-width).
outer-border-width is the width, measured in pixels, of a plain border that is drawn just inside the edge of a chart-or-plot. The value should be a non-negative integer. Zero means that no border is drawn. The default value is zero.
This plain border would be in addition to the exterior window border that is provided by the border property that's common to all widgets, though that property defaults to :none for chart-or-plot.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the outer-horizontal-margin of the argument lamp. This is the number of pixels between the left and right edges of the widget and the lamp image and/or title string that are drawn inside it.
See the description of the lamp control.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the outer-vertical-margin of the argument lamp. This is the number of pixels between the top and bottom edges of the widget and the lamp image and/or title string that are drawn inside it.
See the description of the lamp control.
Generic Function, cg package
Arguments: outline-item
Returns the outline control containing outline-item. outline is a property of the outline-item class.
Function, cg package
This operator is no longer defined and the symbol naming it has been removed.
Generic Function, cg package
Arguments: outline child-item parent-item-if-any
This generic function is called whenever an outline-item is added to the range of a parent outline-item or (for a top-level item) an outline widget. This includes when an item is shifted horizontally, where it is removed from one parent and added to another. The built-in default method does nothing. An application could add a method to update the domain data in a corresponding manner if needed.
parent-item-or-outline will be the parent outline-item to which child-item was added unless it was added as a top-level item, in which case it will be the outline widget itself.
child-item will be the outline-item that was added.
See also add-outline-item and shift-outline-item.
Generic Function, cg package
Arguments: outline item-value
Finds the outline-item in outline whose value is item-value and returns a list of the sub-items of that item. outline should be an outline control.
If you have a handle on the outline-item object itself rather than its value, then it is more efficient to call range on the outline-item instead of calling this function on the value.
Generic Function, cg package
Arguments: outline item kind
This generic function returns a pixmap to display for outline-items when they are in closed state. Though individual outline-items or outline widgets can be assigned their own pixmaps via their closed-pixmap property, an application can alternately assign pixmaps in a more general way by adding methods on this generic function that specialize on the application's outline and/or outline-item subclasses.
The default method returns the value of the closed-pixmap property of the individual outline-item if this is non-nil, otherwise returning the value of the closed-pixmap property of the outline itself if this is non-nil, and otherwise returning the value returned by the function default-closed-pixmap.
The kind argument receives the value of the kind property of the outline-item. The kind property is not used internally, but an application can assign arbitrary values to this property in order to specialize methods of this and other generic functions on it. For example, each outline-item that happens to represent a person could be given a "kind" property of :person. Then an outline-item-closed-pixmap method that uses an (eql :person) specializer for the kind argument would cause each of these outline-items to use a particular pixmap when in closed state.
Generic Function, cg package
Arguments: outline outline-item
The color in which to draw the background of the outline-item that is currently under the mouse cursor when highlight-item-under-mouse is true. Applications could define methods that specifiy custom colors for outline subclasses, or even to use different colors for different outline-item subclasses in the same widget. The default method returns the color that is returned by (make-rgb :red 192 :green 248 :blue 255).
Generic Function, cg package
Arguments: outline outline-item
The color in which to draw the text in the outline-item that is currently under the mouse cursor when highlight-item-under-mouse is true. Applications could define methods that specify custom colors for outline widget subclasses. The default method returns the color that is the variable of the variable black.
Generic Function, cg package
Arguments: outline index
Returns the multiple values (outline-item level parent-item) of the outline-item at index in outline.
Generic Function, cg package
Arguments: outline item kind
This generic function returns a pixmap to display for outline-items when they are in leaf state. Though individual outline-items or outline widgets can be assigned their own pixmaps via their leaf-pixmap property, an application can alternately assign pixmaps in a more general way by adding methods on this generic function that specialize on the application's outline and/or outline-item subclasses.
The default method returns the value of the leaf-pixmap property of the individual outline-item if this is non-nil, otherwise returning the value of the leaf-pixmap property of the outline itself if this is non-nil, and otherwise returning the value returned by the function default-leaf-pixmap.
The kind argument receives the value of the kind property of the outline-item. The kind property is not used internally, but an application can assign arbitrary values to this property in order to specialize methods of this and other generic functions on it. For example, each outline-item that happens to represent a person could be given a "kind" property of :person. Then an outline-item-leaf-pixmap method that uses an (eql :person) specializer for the kind argument would cause each of these outline-items to use a particular pixmap when in leaf state.
Generic Function, cg package
Arguments: outline item-value
Returns the indentation level of the outline-item of outline whose value is item-value. A top-level outline-item has a level of zero.
Generic Function, cg package
Arguments: outline index
This generic function is called whenever the mouse cursor moves over an outline-item of an outline widget. An application could add methods to be notified whenever this happens, such as to show a help message about the value of the outline-item. outline-item-mouse-out will be called when the mouse cursor moves off of the item. The default method does nothing.
outline is the outline widget that contains the outline-item that the mouse has moved over.
index is the index of the outline-item that the mouse cursor has moved over. This is the zero-based index within the set of items that are currently shown, and therefore depends on which items are open at the moment. The outline-item object is not passed for efficiency reasons, because it takes a bit of time to look it up and in most cases it will not be used. If you do want to find the outline-item itself (typically to call value on it to retrieve its value), then pass this index to outline-item-from-index.
Generic Function, cg package
Arguments: outline index
This generic function is called whenever the mouse cursor moves off of an outline-item that it was over in an outline widget. An application could add methods to be notified whenever this happens, such as to no longer show a help string that was shown by an outline-item-mouse-in. The default method does nothing.
When the mouse cursor moves from one item to another, this function will be called before outline-item-mouse-in is called for the next item.
outline is the outline widget that contains the outline-item that the mouse cursor was over.
index is the index of the outline-item that the mouse cursor was over. Pass it to outline-item-from-index if you want to find the outline-item itself.
Generic Function, cg package
Arguments: outline item kind
This generic function returns a pixmap to display for outline-items when they are in opened state. Though individual outline-items or outline widgets can be assigned their own pixmaps via their opened-pixmap property, an application can alternately assign pixmaps in a more general way by adding methods on this generic function that specialize on the application's outline and/or outline-item subclasses.
The default method returns the value of the opened-pixmap property of the individual outline-item if this is non-nil, otherwise returning the value of the opened-pixmap property of the outline itself if this is non-nil, and otherwise returning the value returned by the function default-opened-pixmap.
The kind argument receives the value of the kind property of the outline-item. The kind property is not used internally, but an application can assign arbitrary values to this property in order to specialize methods of this and other generic functions on it. For example, each outline-item that happens to represent a person could be given a "kind" property of :person. Then an outline-item-opened-pixmap method that uses an (eql :person) specializer for the kind argument would cause each of these outline-items to use a particular pixmap when in opened state.
Generic Function, cg package
Arguments: outline outline-item-or-value
Returns the outline-item that is the parent of the specified (by the second argument) outline-item, if any, or nil if there is no parent item.
outline should be the outline widget that contains the items.
outline-item-or-value may be either an outline-item or its value. Passing the item's value is handy when you do not have a handle on the outline-item object, but is less efficient because the item must first be looked up from its value. And if multiple items have the same value, then passing the value may result in a different item than the intended one being found.
Generic Function, cg package
Arguments: outline child-item parent-item-if-any
This generic function is called whenever an outline-item is removed from the range of a parent outline-item or (for a top-level item) an outline widget. This can include when an item is shifted horizontally, where it is removed from one parent and added to another. The built-in default method does nothing. An application could add a method to update the domain data in a corresponding manner if needed.
parent-item-or-outline will be the parent outline-item from which child-item was removed unless it had been a top-level item, in which case it will be the outline widget itself.
child-item will be the outline-item that was removed.
See also remove-outline-item and shift-outline-item.
Generic Function, cg package
Arguments: outline outline-item
Returns the color to use for the background of outline-item in outline when it is the selected item. An application has no need to call this function, but may supply a method to override the default behavior.
The default method (specialized on the outline class for the first argument and the outline-item class for the second) returns the color that is returned by (make-rgb :red 128 :green 240 :blue 255).
See also outline-item-selected-foreground-color.
Generic Function, cg package
Arguments: outline outline-item
Returns the color to use for the text of outline-item in outline when it is the selected item. An application has no need to call this function, but may supply a method to override the default behavior. The default method (specialized on the outline class for the first argument and the outline-item class for the second) returns the color that is returned by a call to system-highlight-foreground-color.
See also outline-item-selected-background-color.
Generic Function, cg package
Arguments: outline parent-item-if-any
This generic function is called whenever the order of a set of sibling outline-items of an outline has changed. The built-in default method does nothing. An application could add a method to reorder the domain data in a corresponding manner if needed.
parent-item-or-outline will be the parent outline-item of the reordered items unless they are top-level items, in which case it will be the outline widget itself.
See also add-outline-item, remove-outline-item, and shift-outline-item.
Generic Function, cg package
Arguments: chart-axis
Returns the value of the overlap-major-and-minor-labels property of a chart-axis. The value may be set at creation time by passing the overlap-major-and-minor-labels initarg, or any time later by calling (setf overlap-major-and-minor-labels).
A boolean value indicating whether the area that is allocated for the major tic labels of a chart-axis in a chart-widget overlaps the area that is allocated for minor tic labels. The default value is t.
When this property is true, both major and minor tic labels are printed just at the ends of the tic marks (with a small gap provided by the margin-inside-major-labels and margin-inside-minor-labels properties). If the label strings are sufficiently long, a major label and a minor label could run into each other. (A chart-widget by default will space things out so that successive major labels do not overlap each other, and so that successive minor labels do not overlap each other, but it does not guarrantee that a major label will not overlap a minor label when this property is true.)
When this property is nil, then major labels are printed in an area that is completely outside the area in which minor labels are printed. This uses up more space, but guarrantees no overlap between major and minor labels. This option also allows minor tic labels to be printed at major tic positions, in addition to the major tic labels; this can be useful, for example, to print a month on every minor tic of an item-axis and a year on every major tic.
See also draw-major-labels and draw-minor-labels.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: basic-pane
Use of this property is deprecated in favor of child-p. (Similarly, use of the :overlapped initarg to make-window is deprecated in favor of the :child-p initarg.)
child-p has the opposite meaning as overlapped, and is t by default rather than nil (except for form windows created interactively, where child-p is nil by default). A child window is one whose parent is a window rather than the screen. A child window is clipped at the interior border of its parent, and moves along with the parent when the parent is moved. The owner of a child window is its parent, and a non-child window (usually called a top-level window) may still have an owner which is a window rather than the screen. The child-p property may not be modified; it may only be passed as the value of the :child-p initarg to make-window and referenced later by calling child-p.
This function returns the value of the overlapped property of the argument. If true, the specified parent will actually be an owner, and the parent will be the screen.
See About child, parent, and owner windows in cgide.html.
The overlapped property may not be changed on an existing window, and must instead be specified with the inspector when designing a window (using a form) or with the :overlapped initarg of make-window. (It can be changed using the inspector when designing a form but not for a running window or control, either in the IDE or in an application.)
Generic Function, cg package
Arguments: comtab
This comtab property determines which command is executed when the user types the keychord of a comtab command, if that keychord is also a global keyboard shortcut or a shortcut in a menu-bar that applies to the same window.
If this property is true, then the comtab's key bindings will take precedence over menu-bar shortcuts (see event-synonym) and global shortcuts (see add-global-keyboard-accelerator). If it is nil, then menu-bar shortcuts and global shortcuts take precedence over the comtab. The default value is nil.
override-menu-bars returns the current value of this property for a specified comtab (command table). The value may be set either by passing the :override-menu-bars initarg to make-instance when creating the comtab, or any time later by calling (setf override-menu-bars). The default value is nil.
The IDE editor is a case where the override-menu-bars option has been enabled. When the IDE editor is selected, the editor's comtab (see ide:text-edit-comtab) and the IDE menu-bar's keyboard shortcuts are both in effect. The IDE menu-bar defines many keyboard shortcuts, and so if you wanted to add some custom editing commands to the IDE editor, then you may find it difficult to find keychords that are not already used by the editor's comtab or the IDE menu-bar. But since the override-menu-bars property of ide:text-edit-comtab is t, it can override shortcuts that are in the IDE menu-bar. Typing reused keychords in the IDE editor will invoke the editor's comtab commands, whereas typing the keychords in any other IDE window will invoke the IDE menu-bar commands. See ide:text-edit-comtab for an example.
Generic Function, cg package
Arguments: menu
This function is no longer used. It was related to the GTK version of CG, which is no longer supported.
Generic Function, cg package
Arguments: basic-pane
This function returns the owner of the argument if there is one. If the argument is a child window or a non-owned top-level window, this function returns its parent (which is a window for a child window or the screen for a non-owned top-level window).
Note that a so-called "non-owned top-level window" is one whose owner is the screen rather than a window.
See About child, parent, and owner windows in cgide.html.
Generic Function, cg package
Arguments: picture-control
Returns the value of the padding property of the argument. The value should be a non-negative integer indicating the number of pixels of extra space to place around each button-info's image but inside the button-info borders of a multi-picture-button (multi-picture-buttons are made up of button-info objects describing the picture buttons) or around the image of a picture-button or static-picture.
For a multi-picture-button, the size of the individual buttons will change to accommodate the specified padding. The images in the button will stay the same size (images are not stretched). See also spacing, which controls the distance between buttons, but not the size of the buttons themselves. (You can see the button area clearly when button-3d-border is t.)
For a picture-button or static-picture, the image will be stretched as needed to fit with the specified padding if stretching is true but will not be stretched if stretching is nil. Note that if padding is too large, the image may disappear and the entire space available is taken up by padding.
Function, cg package
Arguments: stream
Returns a box representing the whole page of stream, relative to the current origin. This is the entire area that can be drawn onto or scrolled into the visible area. stream should be a cg-stream.
If the stream-origin of a window has not been changed from its usual position at 0, 0, then the left and top of the page-box will each be zero, and the right and bottom will be the page-width and page-height of the window. Otherwise the origin position is subtracted from that box to obtain the page-box.
See also npage-box.
Generic Function, cg package
Arguments: stream &optional (stream-units-p t)
Returns the page-height attribute of stream. stream should be a cg-stream. The value may be set at creation time by passing the page-height initarg, or any time later by calling (setf page-height) or set-page-size.
If stream-units-p is true the value is in stream units; otherwise it is in line-heights. See cg-coordinates.html.
The value is always an integer, rounded if necessary when stream-units-p is nil. page-height is the height of what might be called the canvas of the window, only a portion of which may be visible. If you add vertical scrollbars to a window whose page-height is greater than its interior-height, the range of the scrollbars is the page-height and you can scroll the visible portion of the window up and down over that page height.
The function page-height always returns a number, which is either the value returned by explicit-page-height if it returns a number, or else the number returned by default-page-height. The function (setf page-height) may be passed either an explicit page-height number or else nil to make page-height default according to the default-page-height method for the window.
Note that the page-height property uses explicit-page-height as its reader function. This means that a page-height property in the IDE's inspector will be nil unless a page-height has been explicitly assigned. The writer function is still (setf page-height), and so a page-height property may be changed in the inspector either to an explicit number or to nil.
If stream is an instance of the drawable control, this function returns (or sets with setf) the height of the entire "canvas" that may be scrolled onto the drawable. Typically used only when the vertical scrollbar is enabled.
See also page-width and set-page-size.
Generic Function, cg package
Arguments: scroll-bar-mixin
Returns the value of the page-increment property of its argument. This property determines the distance a slider will advance when the PAGE UP or PAGE DOWN keys is pressed.
Used by the PAGE UP and PAGE DOWN keys, or when you click inside the body of the scrollbar between the scroll arrow(s) and the slider. It contains a numeric (fixnum) value relating to the range. If the range is (0 100) and the page-increment is 10, then pressing a PAGE UP or PAGE DOWN key will advance the slider 10/100 of the way along the dialog in that direction.
PAGE DOWN in a horizontal trackbar or horizontal-scroll-bar moves the slider to the right, and PAGE UP moves the slider to the left.
Function, cg package
Arguments: stream &optional stream-units-p
Returns the page-length attribute of stream. If stream-units-p is true, the value is in stream units, otherwise it is in line-heights. It is always an integer, rounded if necessary, when stream-units-p is nil.
Generic Function, cg package
Arguments: printer
Returns the number of the page that is currently printing on the printer stream specified by the argument. The first page is number 1.
page-number is a property of the printer class.
This generic function is not and cannot be setf'able. You must specify a value for this property when a printer stream is created with open-stream. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Generic Function, cg package
Arguments: stream &optional (stream-units-p t)
Returns the page-width attribute of the stream argument. stream should be a cg-stream. The value may be set at creation time by passing the page-width initarg, or any time later by calling (setf page-width) or set-page-size.
If stream-units-p is true, the value is in stream units, otherwise it is in space-widths (the width of the space character in the default font). See cg-coordinates.html.
The value is always an integer, rounded if necessary when stream-units-p is nil. page-width is the width of what might be called the canvas of the window, only a portion of which may be visible. If you add horizontal scrollbars to a window whose page-width is greater than its interior-width, the range of the scrollbars is the page-width and you can scroll the visible portion of the window left and right over that page-width.
The function page-width always returns a number, which is either the value returned by explicit-page-width if it returns a number, or else the number returned by default-page-width. The function (setf page-width) may be passed either an explicit page-width number or else nil to make page-width default according to the default-page-width method for the window.
Note that the page-width property uses explicit-page-width as its reader function. This means that a page-width property in the IDE's inspector will be nil unless a page-width has been explicitly assigned. The writer function is still (setf page-width), and so a page-width property may be changed in the inspector either to an explicit number or to nil.
If stream is an instance of a drawable control, this function returns (or sets with setf) the width of the entire "canvas" that may be scrolled onto the drawable. Typically used only when the horizontal scrollbar is enabled.
See also page-height and set-page-size.
Generic Function, cg package
Arguments: graphical-stream
Returns the current paint operation of the specified stream, which should be a graphical-stream. The value may be changed at any time by calling (setf paint-operation) or with-paint-operation. The initial paint operation of any graphical-stream is po-replace.
A paint operation determines how the colors of new content that is being drawn are combined with the current colors of the stream's pixels to determine the final colors that will appear.
A paint operation value should be the value of one of the following constants: po-replace, po-paint, po-xor, po-invert, po-fill, po-erase, and po-and.
On the Windows platform, an alternate paint operation will not be used for line drawing when *antialiasing* is true, and will not be used for area filling when either *color-gradient-filling* or *alpha-blending* is true. The reason is those variables cause Common Graphics to use the newer GDI+ library of Windows graphics functions, while paint operations are provided only by the older GDI library that Common Graphics uses otherwise.
Here is an example that uses some of the possible values:
(in-package :cg-user)
(let* ((frame (make-window :paint-operations
:class 'bitmap-window
:exterior (make-box-relative 100 200 300 300)))
(pane (frame-child frame)))
;; Starting out with a black background is handy for
;; some paint operations.
(with-background-color (pane black)
(clear-page pane))
;; Draw a basic red block using the default po-replace operation.
(with-foreground-color (pane red)
(fill-box pane (make-box 40 40 200 200)))
;; Use po-paint to merge part of a dark-green block
;; with part of the red block.
(with-paint-operation (pane po-paint)
(with-foreground-color
(pane (make-rgb :red 60 :green 130 :blue 40))
(fill-box pane (make-box 100 100 240 240))))
;; Use po-erase to draw an upper line that erases redness.
(with-line-width (pane 7)
(with-foreground-color (pane red)
(with-paint-operation (pane po-erase)
(draw-line pane (make-position 0 0)
(make-position 300 300)))
;; And finally use po-and to draw a lower line that
;; erases all color EXCEPT redness.
(with-paint-operation (pane po-and)
(draw-line pane (make-position 0 0)
(make-position 300 400))))))Generic Function, cg package
Arguments: stream
Palettes have been implemented only for Windows desktop mode. They will not be implemented for CG/JS mode because they are basically obsolete.
Returns the value of the palette property of stream. stream should be a cg-stream.
Valid values for a palette are either the symbol :rgb or a palette handle (an integer) that was returned by a call to open-palette. When the value is :rgb (the default), the foreground-color and background-color of the window should always be an RGB object, which will be mapped or dithered to one of the 20 system colors (which consist of the 16 standard VGA colors plus four other colors from the end user's Control Panel preferences). When the value is a palette handle, the foreground and background colors should always be an integer index into the color vector that was passed to open-palette.
RGB objects are created with make-rgb. There are some predefined rgb colors like red, blue, black, etc.
Palettes are useful only when the end user may be running Windows in 8-bit (256-color) mode or 16-bit (65,536-color) mode.
Palette handles are created with open-palette.
See cg-color-palettes.html. Among other things, that file discusses when assigning a palette to a window is desirable or necessary.
Generic Function, cg package
Arguments: graphical-stream
Returns the number of entries in the palette of its the specified graphical-stream (see open-palette). If the value of palette for the argument is nil or :rgb, that value is returned rather than a number.
palette-size is a property of the graphical-stream class.
In releases prior to 7.0, there was a palette-size method for pixmaps. This method has been removed. Use bits-per-pixel instead.
Generic Function, cg package
Arguments: printer
Returns the height of the actual paper for the specified printer stream. The height is specified in inches or millimeters (see paper-size-unit).
This property is derived from the paper-size property, and may not be specified programmatically.
paper-length is a property of the printer class.
This generic function is not setf'able.
Generic Function, cg package
Arguments: printer
Returns the paper size available in the argument printer.
paper-size is a property of the printer class.
This generic function is not and cannot be setf'able. This property may be specified with the :paper-size initarg to open-stream when creating a printer stream, though a particular printer driver may or may not pay any attention to the value. Otherwise the property will reflect what the end user has either selected or allowed to default (when available) on the print job dialog that appears by default when a printer stream is created.
It's probably best not to specify this property programmatically unless it is somehow known that the printer being used supports the specified paper size, since otherwise a printer driver may blindly attempt to use a size that it does not really support. This property is typically read after opening a printer stream to find out which standard paper size the application must arrange its output on.
Possible values are:
:letter :letter-small :legal :folio :quarto
:csheet :dsheet :esheet
:tabloid :ledger :statement :executive :note
:a3 :a4 :a4-small :a5 :b4 :b5
:10x14 :11x17
:envelope-9 :envelope-10 :envelope-11 :envelope-12 :envelope-14
:envelope-dl :envelope-c3 :envelope-c4 :envelope-c5 :envelope-c6
:envelope-c65 :envelope-b4 :envelope-b5 :envelope-b6
:envelope-italy :envelope-monarch :envelope-personal
:fanfold-us :fanfold-standard-german :fanfold-legal-germanGeneric Function, cg package
Arguments: printer
Returns either :inch or :mm to indicate whether the paper-width and paper-length properties of the printer stream are in inches or millimeters. If paper-size is :letter, for example, then paper-size-unit will be :inch, paper-width will be 8.5, and paper-length will be 11.
If paper-size is :a4, then paper-size-unit will be :mm, paper-width will be 210, and paper-length will be 297. This property is derived from the paper-size property and may not be specified programmatically.
Generic Function, cg package
Arguments: printer
Returns a keyword indicating the bin from which paper is drawn for the printer stream. This is typically the value that the end user chose on the Page Setup or Print dialog, though it may alternately be passed as an initarg when opening a printer stream with open-stream. The possible values are :only-one, :lower, :middle, :manual, :envelope, :envelope-manual, :auto, :tractor, :small-format, :large-format, :large-capacity, or :cassette.
Generic Function, cg package
Arguments: printer
Returns the width of the actual paper for the specified printer stream. The width is specified in inches or millimeters (see paper-size-unit).
This property is derived from the paper-size property, and may not be specified programmatically.
paper-width is a property of the printer class.
This generic function is not setf'able.
Generic Function, cg package
Arguments: standard-object
Returns the parent of the argument. See also owner. And see About child, parent, and owner windows in cgide.html.
For windows, (setf parent) may be called to change the parent of an existing window to another window or the screen (to change to the screen, setf the value to (screen *system*) -- see screen and *system*). The new parent will also be the owner of the window, even when the new parent is the screen. (Currently there is no way to change the owner of an owned top-level window.)
In releases prior to 6.0, this function returned the owner when the window was a pop-up window (see pop-up. The real parent of a pop-up window is always the screen regardless of what :parent initarg is passed to make-window. It may still have an owner window, however, which is the window with which the window shrinks and closes. If your code calls parent to return the owner of a pop-up window, then you will need to change it to call owner instead.
Generic Function, cg package
Arguments: window
This function is not needed in release 6.0 and later. The function owner now returns the same thing that parent-or-owner returned in releases prior to 6.0 and it should be used instead of those functions. This function is still available for backward compatibility.
Returns the parent or owner of window. The parent is returned unless the parent is the screen and the window has an owner, in which case the owner is returned.
The parent is the window that physically contains a window. It clips the window where it would extend outside the parent, and so the window can be seen only within the interior of the parent. The window also moves and shrinks along with its parent when the parent is moved or shrunk.
The owner is a top-level window that acts partially as a parent. It does move and shrink its owned windows along with itself, and prevents its owned windows from appearing in the Windows taskbar or in the ALT-TAB application-switching pop-up window, even though the owned windows are themselves top-level windows. On the other hand, an owned window is not constrained to the interior of its owner.
In all cases, the window returned from parent-or-owner will be the window that was specified via the :parent argument to make-window, unless of course the parent has been changed with (setf parent). In the general case, the parent that was specified becomes the real parent of the window, and the window has no owner. But if the parent window that was specified is a top-level window, and the :pop-up or :overlapped flag was passed to make-window, then the specified parent becomes the owner of the new window, and the window's parent is the screen.
See also owner, parent, is-child-allowed, and see About child, parent, and owner windows in cgide.html.
Generic Function, cg package
Arguments: lisp-edit-pane file-position type matches-closing in-view
This generic function is called whenever the text cursor in a lisp-edit-pane is moved so that it is just before an opening parenthesis or just after a closing parenthesis, if there is a matching parenthesis within the top-level Lisp form that the text cursor is in. It is also called for matching double-quote characters of literal strings.
There is no need for an application to call this function, but it may add methods to implement side effects. A lisp-edit-pane will automatically draw a mark to indicate the matching parenthesis if it is in view (according to parenthesis-matching-style and parenthesis-matching-color), but an application may also wish to add a status-bar message, for example, particularly if the matching parenthesis is not in view.
The default method that specializes on lisp-edit-pane does nothing. (The IDE editor adds an internal method to its lisp-edit-pane subclass for status-bar messages.)
The method will be called with the following arguments:
lisp-edit-pane is the lisp-edit-pane window where the parenthesis match has occurred.
file-position is the character index of the matching character.
type is either nil for a matching parenthesis or the keyword :quote for a matching double-quote character.
matches-closing is true if the matching character is a closing parenthesis or quote, and nil if it is an opening one.
in-view is true if the matching character is currently scrolled into view, and is nil otherwise.
Generic Function, cg package
Arguments: cg-configuration
Returns the value of the parenthesis-matching-color property of cg-configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
If parenthesis matching is enabled (see parenthesis-matching-style), matching parentheses will flash in this color in lisp-edit-pane windows, both in Common Graphics applications and in the IDE's editors and listeners (in releases prior to 7.0, it applied only to IDE editors and listeners).
See also parenthesis-matching-style, parentheses-matched, and without-parenthesis-matching.
Generic Function, cg package
Arguments: cg-configuration
Returns the value of the parenthesis-matching-style property of cg-configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
This value determines what sort of mark is drawn in a lisp-edit-pane window to indicate the parenthesis or double-quote character that matches the character at the text cursor, to denote the "other end" of a list or literal string. This applies to Common Ggraphics applications as well as to the IDE's editors and listeners.
This option is not supported in CG/JS mode, where the :color-block style is always used. parenthesis-matching-color is supported though.
On Mac OS X, matching characters cannot be drawn directly, so they are drawn with a pop-up window. See *show-parenthesis-matches-as-pop-up-window* and the note after the list of possible styles.
(setf parenthesis-matching-style) may be called to set the value, and in the IDE the option also appears on the editor tab of the dialog displayed by the Tools | Options menu command. See also parenthesis-matching-color, parentheses-matched, and without-parenthesis-matching.
The choices are:
:color-bar: display a vertical bar ( | ) in parenthesis-matching-color next to the matching parenthesis.
:color-outline: enclose the matching parenthesis in a box outline in parenthesis-matching-color.
:color-block: enclose the matching parenthesis in a filled box in parenthesis-matching-color (the matching parenthesis shows through the box).
:inverted-block: enclose the matching parenthesis in a filled box that inverts the foreground and background colors.
:parenthesis-color: display the matching parenthesis itself in parenthesis-matching-color.
:off: no visual parenthesis matching.
If the value of *show-parenthesis-matches-as-pop-up-window* is true, as it normally is on Mac OS X, then parenthesis matching will always behave as if the value of this option were :color-block.
Generic Function, cg package
Arguments: common-status-bar
Returns the list of section widths for common-status-bar. Each width in the list may be either:
a fixnum indicating a fixed pixel-width.
a float between 0 and 1 (non-inclusive), to indicate what portion of the extra space that was not used up by the fixed sections is allocated to that part.
the symbol t. Any extra width of the status-bar that was not used up by the fixed and float sections will be divided evenly amongst any "t" sections.
For example,
(setf (parts my-status-bar)
'(60 40 .5 .3 t))This would allocate the first 100 pixels of my-status-bar's width to the first two sections, then 50% and 30% of the remaining width would go to the next two sections, and whatever is left would go to the last section.
Generic Function, cg package
Arguments: editable-text
Returns the value of the password property of its argument, which must be an editable-text control. This property may be used to prevent others from seeing what the end user is typing into an editable-text control, by displaying an asterisk or other special character for each character that the user actually enters. The real characters are still stored in the string value of the control as usual. Password masking can be switched on and off for an existing editable-text by calling the setf of this function.
The value may be either nil (the default) for ordinary text display without password masking, t to display an asterisk for each real character, or a Lisp character to display that character for each real character.
password is a property of the editable-text class. (In the documentation for some earlier releases, password was incorrectly said to be a property of multi-line-editable-text class as well.)
Generic Function, cg package
Arguments: *dialog-item *
Returns whether anything will be done when paste-selection or insert-selection is called on dialog-item or its widget-window. The value of this property may be set by calling (setf pastable), or it may be set in the inspector when laying out forms in the IDE.
If nil, then paste-selection or insert-selection will do nothing and will return nil. Otherwise they will proceed as usual (though insertion is still done only when there is an applicable method to do it).
The default value is t for text-editing widgets, where text insertion is typically allowed, and nil elsewhere.
There is special behavior when dialog-item is an item-list, that is a single-item-list or a multi-item-list. Pasted values are added as values to the range property of the item-list (rather than selecting pasted values that are already in the range, for example). If the pasted value is a list, then each element of the list will be added as a separate value. Any value that is already in the list (according to the widget's on-change-test function) will not be added again. And there are several possible values of the pastable property that determine where the pasted values will be inserted among the existing values:
nil: Pasting will not be done.
t: Acts like :before.
:before: Inserts the values just before the value that has the keyboard focus, or at the top if there is no such value. Typically one of the current values will have the focus.
:after: Inserts the values just after the value that has the keyboard focus, or at the top if there is no such value.
:top: Inserts the values at the top of the list.
:bottom: Inserts the values at the bottom of the list.
:sorted: Sorts all of the values that are in the list. When the on-sort-predicate property of the widget is nil (as it is by default), all types of values will be sorted alphanumerically, and otherwise they will be sorted by the on-sort-predicate function.
:ask: Asks the user each time in a pop-up menu which of the above choices to use.
A combo-box can cut and paste text in its type-in pane if it is typable (as well as cuttable and/or pastable), but cutting and pasting will never remove or add items to its range as with an item-list.
See also cuttable and cg-clipboard.html.
Generic Function, cg package
Arguments: window
Sets the character format of the currently selected text in window to reflect the character-format instance that is currently the value of the global variable *copied-character-format*. window must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
The Edit | Paste Format command on the rich edit menubar calls this function. (That command does not appear on the Allegro CL Edit menu.)
See copy-character-format, which sets the value of *copied-character-format* to a character-format instance.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: window-or-widget
Retrieves an object from the clipboard and pastes it into the specified window or widget. Returns the object that was pasted and its clipboard format.
This is largely a convenience function that combines other exported functionality as it is typically used. An application menu command could call this function directly.
window-or-widget should an instance of the basic-pane, dialog-item or screen class or one of their subclasses.
The default paste-command and insert-command methods are shown below, in case you need to use some variation of this typical behavior. These methods first pass the action down to the bottommost selected-window of the window that was passed in, and call default-clipboard-format to find what type of object is typically pasted into this type of window. They then call top-clipboard-value-of-type to retrieve a value of that type from the clipboard, and finally call paste-selection or insert-selection to paste that object into the specified window or widget.
(defmethod paste-command ((stream cg-stream))
(let* ((child (selected-window stream)))
(if* child
then (paste-command child)
else (paste-or-insert-command stream nil))))
(defmethod insert-command ((stream cg-stream))
(let* ((child (selected-window stream)))
(if* child
then (insert-command child)
else (paste-or-insert-command stream t))))
(defun paste-or-insert-command (stream insert?)
(setq stream (or (dialog-item stream) stream))
(let* ((format (default-clipboard-format stream))
(object (with-object-locale (stream)
(top-clipboard-value-of-type format))))
(and object
(if insert?
(insert-selection stream object)
(paste-selection stream object)))))There are also methods on dialog-item that simply pass the action to the widget's window when the widget is on a parent window.
See copy-command for discussion of the calls to dialog-item and with-object-locale in this code.
See cg-clipboard.html.
Generic Function, cg package
Arguments: window-or-widget object
Adds object to the current content of window-or-widget if it knows how to do so, generally at the "current position" in the window or widget. Returns object if a paste was done, and nil otherwise. This function is called by paste-command, which grabs an object off of the clipboard to pass to this function. An application could call either function, or add methods to either in order to extend the clipboard functionality. An application might call this function with a value that was retrieved by calling copy-selection or cut-selection.
window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass. object may be any value.
The default method does nothing (and therefore returns nil). The methods for editable-text-pane and text-edit-pane replace the selected text with a printed representation of the object if any text was selected, and otherwise insert the object at the text cursor position. The combo-box-pane method does likewise, but only if the typable property of its associated combo-box is true.
The bitmap-pane method calls copy-to-stream to copy the object to the window if it is a pixmap, and otherwise does nothing. The drawable-pane method does that as well, but only if its use-bitmap-stream property is true.
The methods for single-item-list-pane and multi-item-list-pane add the bbject as a new value to the range of the associated single-item-list or multi-item-list widget. If the object is a list, then one item is added for each member of the list. If the pastable property of the widget is :after, then the new item is added just after the currently focused item, and otherwise it is added just before it (that is, at the "current position" in the range).
The method for dialog-item simply calls paste-selection on the window of the dialog-item if the widget is currently on a parent window.
An around method on widget-window causes nothing to be done if window-or-widget is either a dialog-item or its associated window, and the widget's pastable property is nil. By default, pastable is true only for text-editing widgets.
An anomaly: The only way to paste formatted text into a rich-edit-pane using this function is to first make sure that rich text is currently on the clipboard, and then to call this function with nil as the object argument. (Or just call paste-command.) If the object received here is non-nil, then it will always be pasted as a simple string, using the formatting of the window at the insertion point. Calling (setf rich-edit-range) is a way to insert formatted text without using the clipboard.
See copy-selection for a note abouting adding additional methods for other types of widgets.
In releases prior to 7.0, this function passed its action to the lowest selected descendent child window of the specified window, though some applications may not desire such automatic redirection. The functions focus-component, get-focus, or selected-window may be useful for finding a suitable widget or window to pass to this function.
See cg-clipboard.html.
Generic Function, cg package
Arguments: app
Returns the value of the path property of app. This property is the path of the currently-running Lisp executable. Its value can be used by applications to find files that have been installed in the same directory as the main application executable file (or in related directories).
path is a property of the app class.
Generic Function, cg package
Arguments: rich-edit-pane link-string
Takes a link-string that was clicked on in rich-edit-pane (which must be an instance of the rich-edit-pane class) and should return the path of an .rtf file that should be opened for that link.
The default method merely maps the link-string to an .rtf file in the same directory as the current file of the rich-edit-pane. To do more complex link mappings, an application should supply a pathname-for-link method for its subclass of rich-edit-pane.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: stream position &optional result-rgb
Returns the color of the pixel at position in stream. The value will be stored in result-rgb (which must be a rgb color object, see make-rgb) if that value is specified.
position must be a position (see make-position). stream should be a cg-stream.
setf can be used with this function to set the value of a pixel. This is one way to draw something one pixel at a time. In the following example, a series of calls to (setf pixel) will draw a red line in the bitmap-pane of a bitmap-window:
(setq win (make-window :mywin :class 'bitmap-window))
(setq pane (frame-child win))
(dotimes (i 100) (setf (pixel pane (make-position 10 (+ 5 i))) red))To avoid consing a position object on each call, call pixel-x-y instead, or use the with-positions macro. pixel-x-y is the variant of this function that takes coordiates as arguments rather than position objects.
CG/JS Note: When running in CG/JS mode, the value of the variable white is always returned, because we have not found a way to implement this. But calling (setf pixel) works.
Generic Function, cg package
Arguments: window-or-screen x y &optional result-rgb
Returns the color of the pixel at the position in stream specified by the x and y arguments. The value will be stored in result-rgb (which must be a rgb color object, see make-rgb) if that value is specified. stream should be a cg-stream.
See also pixel.
Function, cg package
Arguments: pixel-size
Returns a point size that is equivalent to the specified pixel size. The argument and returned value may be any real number. There are approximately 72 points in an inch, but since the actual monitor size is unknown, the point size may not reflect reality very closely.
See also stream-units-per-inch.
Generic Function, cg package
Arguments: object
Returns (or sets with setf) the pixmap that will be displayed for a picture-button or static-picture control or for an individual button of a multi-picture-button.
pixmap is also used by Inspect dialog windows to provide visual identifiers of objects. In the IDE, the inspector uses the pixmap returned by this generic function to point out objects of various types in its drop-down history list. The inspector may be customized to show additional pixmaps for other types of objects by defining pixmap methods. For example, the following method would cause the radio-button pixmap to be displayed thereafter in the inspector's history list for any symbol in the list.
(defmethod pixmap ((object symbol))
(find-pixmap 'radio-button))pixmap is a property of the button-info, picture-button, and static-picture classes.
Generic Function, cg package
Arguments: object
Returns an association list that maps arbitrary application values to pixmaps that represent those values visually. The value may be set at creation time by passing the pixmap-alist initarg, or any time later by calling (setf pixmap-alist). This is a property of the static-picture widget and the pixmap-column-mixin class. The default value is nil.
The value should be a list where each element is a list of an application value and a pixmap name. For a static-picture, each application value should be something that the application might place into the value property of the widget. For a grid-column of the pixmap-column-mixin class, each application value should be something that might be returned when read-cell-value is called. For either type of object, each pixmap name should be the name of a pixmap that has been cached by calling cache-pixmap.
When the interface object is given an application value to display, the pixmap-alist will be searched for the value, using the pixmap-value-test function to test when two application values are equivalent. If the application value is found in the alist and a pixmap is found for the corresponding pixmap name, then the pixmap is displayed; otherwise the interface object will be blank. The pixmap will fill the available area if the stretching property is true, and the user may cycle through the available pixmaps and values interactively if the user-modifiable property is true.
A pixmap value may also be nil. The interface object will be blank in this case just as it is for values that are not included in the association list, but an explicit nil can be useful to allow the user to interactively select an application value that should be represented by blankness.
With the following pixmap-alist, the application value :none would result in a blank interface object, the application value :partial would draw the pixmap named :key, and the application value :full would draw the pixmap named :key-special.
((:none nil)
(:partial :key)
(:full :key-special)Generic Function, cg package
Arguments: pixmap
Returns the handle to the device-dependent bitmap for the main (not mask) texture of the argument pixmap, if it has been given one by calling open-pixmap-handle, and otherwise returns nil. This function is useful for determining whether the pixmap currently has such a handle, though the particular handle is not useful for Common Graphics code. This handle corresponds to the main texture stored in the texture property of the pixmap; see mask-handle for the handle corresponding to the mask texture.
pixmap-handle is a property of the pixmap class. See also close-pixmap-handle.
Generic Function, cg package
Arguments: pixmap-interface
Returns (or sets with setf) an icon that will be displayed for a picture-button or static-picture control or for an individual button of a multi-picture-button. The icon may be specified either as an icon handle (a non-negative integer) or as a symbol that is bound to an icon-handle. The icon handle may be either one of the built-in icon handles (which are the values of error-icon, warning-icon, question-icon, information-icon, and application-icon) or may be an icon handle that was returned by calling create-icon-handle.
A pixmap-icon can be used for an object instead of a pixmap, but both may not be used simultaneously. When an object's pixmap-icon is set, its pixmap is set to nil. When an object's pixmap is set, its pixmap-icon is set to nil.
pixmap-icon is a property of the button-info, picture-button, and static-picture classes.
Generic Function, cg package
Arguments: pixmap-interface
Returns (or sets with setf) the symbol name of the pixmap that will be displayed for a picture-button or static-picture control or for an individual button of a multi-picture-button. When setting this value, the pixmap that is set should have been placed into the set of cached pixmaps at some point by calling cache-pixmap on it.
pixmap-name is a property of the button-info, picture-button, and static-picture classes.
Generic Function, cg package
Arguments: pixmap-interface
Returns (or sets with setf) the path namestring of the .bmp pixmap file from which the pixmap instance to display on a picture-button or static-picture control or individual button of a multi-picture-button was originally read (if any). When this value is set, the set of cached pixmaps is searched for a pixmap that has that path namestring as its source, and if one is found then that pixmap is used. Otherwise load-pixmap is called on the path namestring, a pixmap object is created from the information that is read, the pixmap is cached by calling cache-pixmap on it so that it may later be retrieved by calling find-pixmap on its name (or on its source path namestring), and the new pixmap is used for the control.
pixmap-source is a property of the button-info, picture-button, and static-picture classes.
Generic Function, cg package
Arguments: pixmap-interface
Returns (or sets with setf) whether the pixmap that is used by a picture-button, static-picture, or individual button of a multi-picture-button will use a handle to a device-dependent pixmap. When this property is changed, either open-pixmap-handle or close-pixmap-handle is called internally on the pixmap of the object that was passed in to establish whether it uses a pixmap handle.
pixmap-use-handle is a property of the button-info, picture-button, and static-picture classes.
Generic Function, cg package
Arguments: object
Returns the name of a function that is used to determine whether two application values of a static-picture or pixmap-column-mixin
The function should take two arguments, and return true if they are considered equivalent and nil otherwise. The function is called to locate a real application value in the pixmap-alist of the interface object, to find the corresponding pixmap to display.
Generic Function, cg package
Arguments: widget
Returns the plain-border-width of the argument control.
Function, cg package
Arguments: string face point-size &key boldp italicp underlinep color
Creates and returns a rich-text string with the text of the specified plain-text string and with the specified character formatting. face should be the keyword name of an installed font face. point-size is the size of the font in points. boldp, italicp, and underlinep each turn on the corresponding font attribute when true. color should be an rgb object (see make-rgb) indicating the foreground color of the text. If string is the null string (a string of length zero), then the value of *empty-rtf-string* is returned.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: object
Returns argument's property list (abbreviated plist). Among the objects acceptable as an argument are dialog-item, menu-item, outline-item, simple-stream (includes all windows and menus, along with other streams not related to Common Graphics) hotspot, project, and symbol (for symbols, plist calls symbol-plist).
A property list is a list with an even number of elements. The odd elements are keys (typically named by symbols) and the even elements the values corresponding to the keys. The system uses object property lists. Users should add and remove their own key/value pairs but should not remove or modify the system key/value pairs. Also, avoid common words for key names (except on your application's own symbols) as they may already be used by the system.
function, cg package
Arguments: plot-widget value-type value-index &key object-index object-id
Returns an individual value that is in a plot-widget. This could be a value that was added by calling set-plot-value or a value that is returned by the widget's plot-value-returner function if it has one. The value will be nil if the plot does not define a value for the specified value-type, value-index, and object, and otherwise it will be a number.
plot-widget is the widget to be accessed.
value-type is the type of value to return. This argument may be one of the following keywords:
:x: The X coordinate of the value-index'th point to plot for some object.
:y: The Y coordinate of the value-index'th point to plot for some object.
:x-high: an optional value that's normally greater than the X coordinate. Typically represents an error range.
:x-low: an optional value that's normally less than the X coordinate.
:y-high: an optional value that is normally greater than the Y coordinate.
:y-low: an optional value that's normally less than the Y coordinate.
:icon-size: an optional size for a built-in icon that is drawn at X,Y.
value-index is the zero-based index of the plot value to access.
The keyword arguments are:
object-index is the zero-based index of the chart object to access, or nil to not specify an object index. The default is zero if neither this argument nor object-id is true. object-index takes precedence if both are true. The widget's chart-object-id-equality-test is used to find a matching object-index.
object-id is the arbitrary ID of the chart object to access, as defined in the chart-objects property, or nil to not specify an ID.
See plot-widget.
Generic Function, cg package
Arguments: plot-widget
The value of this property can be a function (or the name of a function) that supplies the data values to be displayed in a plot-widget. Otherwise it should be nil (the default), in which case the plot's data must be supplied by calling set-plot-value multiple times. plot-widget must be a plot-widget.
The function will be called automatically every time the plot-widget draws a value. The arguments to the function indicate which plot value index and object it is drawing, and which type of value. The function should return a number to display, or else nil if that type of value should not be drawn for the specified object and value index.
Generally when using a plot-value-returner you should also specify the plot-values-max-index property of the plot-widget, and maybe also the plot-values-min-index property, to tell the plot the range of value indexes that it should pass to the function. And if the plot contains more than one object, then you should also set up the chart-objects property to tell the plot the range of object indexes that it should pass to the function (and typically their object IDs as well).
Note that in the inspector this property is on the Events tab because its value is a function, though it is not actually handling window system events.
See the page for the plot-widget class for an example of a plot-value-returner function.
The parameter list of a plot-value-returner function should be this:
Arguments: plot-widget value-type value-index object-index object-id
These arguments are:
plot-widget is the plot being drawn.
value-type is the type of value that is being drawn. This will be one of the following keywords:
:x: the X coordinate of the point that is being plotted. This is always measured along a horizontal axis.
:y: the Y coordinate of the point that is being plotted. This is always measured along a vertical axis.
:x-low: an optional value that's normally less than the X coordinate.
:x-high: an optional value that's normally greater than the X coordinate.
:y-low: an optional value that's normally less than the Y coordinate.
:y-high: an optional value that's normally greater than the Y coordinate.
:icon-size: an optional size for a built-in icon drawn for a data point.
(If a particular type of value will never be drawn, then for efficiency that value type could be removed from the value-types property of the plot-widget. That will prevent the plot-value-returner function from ever being called for that type of value.)
value-index is the zero-based index of the point being drawn.
object-index is the zero-based index of the chart object being drawn.
object-id is the arbitrary ID of the chart object being drawn. This will be meaningful only if you have set up the chart-objects property of the plot-widget to specify object IDs; otherwise an object-id will default to the object-index.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the plot-values property of a plot-widget. The value may be set at creation time by passing a plot-values initarg to make-instance, or any time later by calling (setf plot-values).
This property contains a set of values that are displayed in a plot-widget. This tree is normally built indirectly by successive calls to set-plot-value. Values are looked up here when the plot is being drawn, or when an application calls plot-value.
An application normally does not need to access this property directly, though it could build the value itself and call (setf plot-values) to set all of the plot's values at once. Here is an example of a form that would return a valid plot-values value:
(vector (vector (list :x 2 :y 3) (list :y 4 :x 9 :y-low 4.2)
(list :x 3 :y 6.5 :icon-size 6)
(list :x 1.3 :y 6.5 :x-low 1.1 :x-high 1.6)
(list :x 1.3 :y 7.5) (list :x 1.3 :y 8.5)
(list :x 3.3 :y 8.5) (list :x 12 :y 3))
(vector (list :x 4.3 :y 8.5) (list :x 5.3 :y 8.5)
(list :x 6.3 :y 6.5) (list :x 6.3 :y 4)))The value is a vector where each element of the vector represents one chart object (see chart-objects). Each chart object element is itself a vector of points that will be plotted for that object. Each point is a property list whose keys can be any of the valid values for the value-type argument to set-plot-value.
To avoid building this vector of values at all, use a plot-value-returner function instead.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the plot-values-max-index property of a plot-widget. The value may be set at creation time by passing a plot-values-max-index initarg to make-instance, or any time later by calling (setf plot-values-max-index).
plot-values-max-index is the index of the last plot value of a plot-widget that should be displayed at the current time. The value should be a non-negative integer, or else nil for no maximum. The default value is nil.
If set-plot-value has been used to add values to the plot, then any value whose index is greater than this property value (if it is a number) will not appear in the plot. When the property value is nil, then no items are excluded. This property can be used to display a subset of collected values that are of interest at the moment.
If instead a plot-value-returner function is used for looking up plot data, then this property should always be set to a non-negative integer to tell the plot the maximum value index that it should pass to the plot-value-returner function. Otherwise the plot-widget has no way of knowing how many values your function is prepared to return. (The property will arbitrarily default to 100 in this case, though that would usually not match your available data.)
This property is the maximum index that will be included, rather than the number of indexes to include. So for a plot-value-returner function to cover all values from a 100-element vector, for example, the value of this property should be 99 rather than 100.
If a plot-value-returner function is used, and some chart objects have more data points than others, then this property should be set to the high enough to cover the object that has the most points. And the plot-value-returner function should return nil (rather than breaking) if it is passed an index for some other object that is beyond the number of data points for that object.
See also plot-values-min-index.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the plot-values-min-index property of a plot-widget. The value may be set at creation time by passing a plot-values-min-index initarg to make-instance, or any time later by calling (setf plot-values-min-index).
plot-values-min-index is the index of the first plot value of a plot-widget that should be displayed at the current time. The value should be a non-negative integer, or else nil to default to zero. The default value is nil.
If set-plot-value has been used to add items to the plot, then any item whose index is less than this property value (if it is a number) will not appear in the plot. When the property value is nil or zero, then no items are excluded. This property can be used to display only a subset of collected values that are of interest at the moment.
If instead a plot-value-returner function is used for looking up plot data, then this property could be used if your function handles a range of value indices that does not begin at zero.
See also plot-values-max-index.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the plot-view property of a plot-widget. The value may be set at creation time by passing a plot-view initarg to make-instance, or any time later by calling (setf plot-view).
The value is always an instance of the plot-view class, which draws a plot-widget's data. If you do not pass a plot-view instance as the value of the :plot-view initarg when creating a plot-widget, then a default instance is created automatically.
Generic Function, cg package
Arguments: text-edit-pane
The function returns two values: (1) the font point size of the first character of the selected range of text-edit-pane, and (2) true if and only if the entire selection is the same point-size.
The setf function sets the font point size of the selected range of text-edit-pane to value, which should be an integer.
text-edit-pane must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: point-size
Returns a pixel size that is equivalent to the specified point size. The argument and returned value may be any real number. There are approximately 72 points in an inch, but since the actual monitor size is unknown, the point size may not reflect reality very closely.
See also pixels-to-points for additional notes, and stream-units-per-inch.
Function, cg package
Arguments:
Removes the top value from the Lisp clipboard stack and returns it. The value that then remains on the top of the Lisp clipboard stack is copied onto the Windows clipboard for potential pasting into other applications.
A symbol denoting the Windows clipboard format of the removed value is returned as a second value. This symbol is either :text, :rich-text, or :pixmap, where :text indicates that the removed value is a Lisp string, :rich-text indicates a Lisp string that specifies a piece of rich text (which could be inserted into a rich-edit-pane by calling (setf rich-edit-range), and :pixmap indicates a Common Graphics pixmap object.
A simpler function for dealing directly with the system clipboard (when you don't care about the Lisp clipboard stack) is clipboard-object.
See cg-clipboard.html.
Generic Function, cg package
Arguments: window
Returns the pop-up property of a window. If pop-up is true, it indicates that the window is intended for use as a modal window.
Passing the :pop-up argument to make-window as true (or toggling the pop-up property of a form window to true in the inspector) causes certain other properties to be coerced to values that are typical for modal windows, ignoring any other values that might be passed explicitly to make-window. Specifically, child-p is coerced to nil so that the window is always a top-level window, the initial state will be :shrunk so that the window is not seen until it is invoked by calling pop-up-modal-dialog (typically), minimize-button is coerced to nil since it is not appropriate to shrink a window that demands immediate attention, maximize-button is coerced to nil to prevent the minimize button from appearing at all (it would be present in a grayed out state if the maximize-button were turned on) and because modal windows typically are not designed to be maximized, and scrollbars is coerced to nil because modal windows conventionally do not scroll.
A modal window does not need to use the pop-up property; it is basically a shortcut that can be used in place of remembering to specify various property values that are typical for modal windows. If one or more of the coerced values is not appropriate for a given modal window, then the window can be created without specifying pop-up as true.
NOTE: child-p must be nil for modal windows! In the previous paragraph, we said that a modal window need not have pop-up set to true, because pop-up is a shortcut to specifying other property values. However, if you do create a window to be invoked with pop-up-modal-dialog and do not specify the :pop-up initarg to make-window as true (or set the pop-up property to true), then be sure to at least specify the child-p initarg or the child-p property as nil (which would have been coerced had pop-up been true). child-p defaults to true, and pop-up-modal-dialog does not work on child windows.
The pop-up property may not be changed on an existing window, and must instead be specified with the :pop-up initarg of make-window. (It can be changed using the inspector when designing a form but not for a running window, either in the IDE or in an application.)
The default value of the pop-up property is nil for all windows. In releases prior to 6.0, pop-up defaulted to t when the value of the :widgets initarg to make-window was true, since such windows are often used as modal dialogs.
pop-up is a property of the form class. See About child, parent, and owner windows in cgide.html.
Function, cg package
Arguments: stream title prompt &optional initial-color show-custom-colors disable-custom-colors
Pops up a color-choice dialog and returns the color chosen by the user or nil if no color is chosen or the dialog is canceled. The keyword arguments specify the appearance of the dialog when it is shown.
The title and prompt arguments do nothing in Microsoft Windows because this function invokes the color dialog that is built into Windows, and it does not allow specifying a title or prompt. This function is deprecated in favor of ask-user-for-color.
Function, cg package
Arguments: window-or-screen initial-string search-backwards-p match-exactly-p &key (allow-match-exactly t) (allow-search-backwards t)
Displays a modal dialog asking the user to specify a search string and a few options for doing a search for that string. This function does not do an actual search, and instead simply returns the values specified by the user in the dialog. It is then up to the application to perform a search in some application-defined way.
window-or-screen is typically the window in which the search will be done, though it can actually be an arbitrary window or nil. If nil, then the stream returned by selected-window-or-screen is used. It is used in two ways: (1) The modal dialog is positioned with respect to this window according to the usual internal call to position-utility-dialog, and (2) the top-level-window of window will be passed as the stream argument to pop-up-modal-dialog, to disable user gestures on that window and all of its other owned windows while the modal dialog is present.
initial-string should be a string to be displayed in the search-string widget when the dialog appears. Use the null string to cause the widget initially to be empty.
search-backwards-p determines whether the check-box on the dialog for requesting a backward search will be initially checked. If true, then the widget will be checked, and if nil it will not be.
match-exactly-p determines whether the check-box on the dialog for requesting an "exact match" will be initially checked. If true, then the widget will be checked, and if nil it will not be. This option is typically used to specify whether the search will be case-sensitive or case-insensitive.
allow-match-exactly determines whether the check-box on the dialog for requesting an "exact match" will be available so that the user may change its value. If true, then it will be available; if nil, then it will not be.
allow-search-backwards determines whether the check-box on the dialog for requesting a backward search will be available. If true, then it will be available; if nil, then it will not be.
Three values are returned when the user exits the dialog. If the user cancels the dialog, then these three values will all be nil. Otherwise the values will be (1) the string in the search-string widget, (2) the value of the search-backwards check-box (true or nil), and (3) the value of the match-exactly check-box (true or nil).
Function, cg package
Arguments: choices &key (sortp t) (sort-predicate #'string<) (sort-key #'identity) on-print (stream (screen *system*)) horizontal-justification vertical-justification position on-help
Calls pop-up-menu to display a list of choices, returning the choice selected by the user. The added feature of this function is that it prepends consecutive letters of the alphabet to the displayed menu-item strings to allow the user to quickly choose an item with the keyboard. If there are no more than 26 choices in the menu, then any choice may be made by typing the single shortcut letter displayed at the left end of the menu-item. If there are more than 26 choices, then multiple menu-items will share shortcut letters, and the user may need to type a shortcut letter multiple times until the desired item is highlighted, and then press the ENTER key to choose the highlighted item.
choices are arbitrary values from which the user can choose. The on-print function will convert these values to strings to display on the menu from top to bottom. Shortcut letters are prepended to the displayed strings automatically. A list member may be the symbol menu-separator or its global value to insert a horizontal separator line into the menu at that position; this is suitable only when sortp is nil.
sortp, if specified, should be either true or nil. If true, then the items in the choices list will first be sorted by the sort-predicate function before being displayed. The default value is t, so :sortp nil should be specified to avoid sorting the items.
sort-predicate, if specified, should be a funcallable object (a function object or function name). The default value is the function string<. The function should take two arguments, as with the predicate argument to sort. If sortp is true, then the items in the choices list will be sorted by this function.
sort-key, if specified, should be a funcallable object (a function object or function name) or nil. The default value is nil, which acts as if the identity function were specified. The function should take one argument, as with the key argument to sort. If sortp is true, then the items will be passed to this function and the returned values will be compared with sort-predicate.
on-print, if specified, should be either nil, a function object, or a function name. The default value is nil. If nil, strings in the choices argument will appear as if printed by princ, and symbols will appear as if printed by prin1. If a function, the function should take a single argument, which is an item from the choices list, and all items will appear as if printed by the on-print function. Note that the sort, if done at all, is done on the actual items in the choices list rather than on the strings returned by the on-print function.
stream is either the screen or else a window that will serve as the owner of the pop-up menu. The default value is the screen (see screen). The position argument is relative to this stream.
horizontal-justification and vertical-justification are passed onward to pop-up-menu. See that function for the possible values. These parameters are new to this function in release 11.0.
position is the position relative to the upper-left interior corner of the specified stream at which the upper-left corner of the pop-up menu will appear. The default is offset a bit from the current position of the mouse cursor.
on-help, if specified, should be a funcallable object (a function object or function name) or nil. The default is nil. A function may be used for displaying status bar messages as the user highlights individual menu items. The function should take a single argument, which will be one of the values in the choices list, and it should return a string that can be displayed in a status bar. The strings will be displayed in the status bar of the specified stream, if it has a status bar, or else in the status bar of the first ancestor window of that stream that has a status bar, if any.
This function returns the item from the choices list that was chosen by the user, or nil if the user cancels from the menu by pressing the ESCAPE key or clicking off the menu.
Multiprocessing note: The keyboard shortcuts for a pop-up menu will work only if the window that had the keyboard focus at the time pop-up-menu was called was created by the process that is calling pop-up-lettered-menu. Otherwise the keystrokes will go to the focused window in the other process. For example, the keyboard shortcuts will not work when evaluating a call to pop-up-lettered-menu directly in the initial IDE listener pane, because the IDE will evaluate the expression in the Listener 1 process, though the currently focused window (the listener pane) was created in the IDE GUI process.
An alternative way to ask the user for a choice from a list is to call ask-user-for-choice-from-list. This function may be better when the list of choices is large, as it uses a scrolling single-item-list or multi-item-list. For four choices or fewer, ask-user-for-choice may be used.
Examples:
(pop-up-lettered-menu (list "one" "two" "three") :sortp nil)displays a menu
a one
b two
c threewhile
(pop-up-lettered-menu (list "one" "two" "three") :sortp t)displays a menu with the entries alphabetical:
a one
b three
c twoand
(pop-up-lettered-menu (list "one" "two" "three") :sortp t
:on-print 'capitalize-object)displays a menu with the entries alphabetical and capitalized:
a One
b Three
c TwoGeneric Function, cg package
Arguments: menu &optional window-or-screen position horizontal-justification vertical-justification button
This function returns two values after displaying a pop-up-menu at the mouse cursor or at an arbitrary position. If a menu-item is chosen by the user, it then calls handle-menu-selection on the chosen menu-item and returns the value returned by handle-menu-selection. (By default the return value will be the value of the selected menu-item, since the default handle-menu-selection method returns the value returned by the menu's on-click function, and the default on-click function of a menu simply returns the menu's value.) This function returns nil if the user cancels from the menu by clicking outside the menu or pressing the ESCAPE key. A second returned value is t if the user chose an item or nil if the user canceled the menu.
menu is the menu to display. Menus are created by calling open-menu.
window-or-screen is a window or the screen. The default value is the screen. This argument is relevant only when the position argument is passed, in which case the position is in this stream's coordinate system. In an application with multiple Common Graphics threads, this argument should not be a window in a thread other than the thread that is calling pop-up-menu, because that would prevent keystrokes from alternately being used to select a menu item or exit the menu.
position may be either nil to place the menu at the current mouse cursor position or a position (see make-position) to place the menu at an explicit position. The default is nil. The position should be in the device coordinates of stream; that is, relative to the upper-left interior corner of the window or screen.
horizontal-justification may be either nil, :left, :center, or :right to indicate which edge or center of the menu should horizontally align with the specified menu position. (If position is nil, this aligns the specified part of the menu with the mouse cursor.) The default is :left, and nil is interpreted as :left.
vertical-justification may be either nil, :top, :center, or :bottom to indicate which edge or center of the menu should vertically align with the specified menu position. (If position is nil, this aligns the specified part of the menu with the mouse cursor.) The default is :top, and nil is interpreted as :top.
button may be either :left or :right to indicate which buttons may be used to select an item from the menu. :left indicates that only the left button may be used. :right indicates that either the left or right button may be used. Passing :right may be particularly useful for menus that were invoked by a right click (typically in a custom mouse-right-down method), since this allows the user to optionally hold the button down while dragging to the desired item and then to release the mouse button to select the item and exit the menu with a single click. The default is :left.
See also the more specialized functions pop-up-lettered-menu and pop-up-shortcut-menu. Also, an alternative way to ask the user for a choice from a list is to call ask-user-for-choice-from-list. This function may be better when the list of choices is large, as it uses a scrolling single-item-list or multi-item-list. For four choices or fewer, ask-user-for-choice may be used.
Microsoft Windows Note: to make it easy for the user to select a choice or to cancel a pop-up menu, you may want to ensure that a window from the same process has the keyboard focus, or at least that such a window is present on the screen. In Microsoft Windows, keypresses will apply to a pop-up menu only if the window that currently has the keyboard focus was created in the process that popped up the menu. Otherwise the Escape key will not dismiss the menu, and a choice cannot be made with the keyboard. Clicking the mouse outside a pop-up menu will dismiss the menu only if the click is on a window that either was created in the process that is calling pop-up-menu, or is in a window hierarchy that contains such as window).
Example: Here is a simple example where either clicking the right mouse button or pressing the spacebar will create a pop-up menu on the fly and call pop-up-menu to display it, and then close the menu afterwards to free up the operating system resource for the menu.
(defclass my-frame (frame-window)())
(defmethod mouse-right-down ((window my-frame) buttons cursor-pos)
(declare (ignore buttons cursor-pos))
(show-my-menu window))
(defmethod virtual-key-down ((window my-frame) buttons
(key-code (eql vk-space)))
(declare (ignore buttons))
(show-my-menu window))
(defun show-my-menu (window)
(let* ((menu (open-menu (list (make-instance 'menu-item
:title "~Yellow"
:value 'yellow)
(make-instance 'menu-item
:title "~Green"
:value 'green)
(make-instance 'menu-item
:title "~Cyan"
:value 'cyan))
'pop-up-menu (screen *system*)))
answer)
(unwind-protect
(progn
(setq answer (pop-up-menu menu (screen *system*) nil
:left :center :right))
(when answer
(setf (background-color window)(symbol-value answer))
(invalidate window))) ;; redraw in new color
(close menu))))
(make-window :color-test
:class 'my-frame
:title "Right-Click or Press the Spacebar to Change Color")Function, cg package
Arguments: choices &key (on-print 'princ-to-string) (stream (screen *system*)) position case-insensitive on-help
This function takes a list of pre-sorted choices and presents them to the user as a series of pop-up menus (by calling pop-up-menu one or more times). The main purpose of this function is to make it easy to select one of many choices.
This function is challenging to describe. We will start with a simple example where we do not use the keyword arguments, then we will describe the arguments in more detail, then we have a more complex example.
choices must be list of objects arranged so their printnames (as created by the function which is the value of the on-print argument) are in alphanumeric order. Just to use strings (assuming default on-print), ("Jones" "Smith" "Smits" "Watson" "Williams" "Wilson") is a suitable value. ("Smith" "Smits" "Watson" "Williams" "Jones" "Wilson") is not. (The menu presenting algorithm may get confused if the printnames are out of order.) So this call:
(pop-up-menus-for-many-sorted-choices '("Jones" "Smith" "Smits"
"Watson" "Williams" "Wilson"))causes this menu to be displayed:
Note that, for reasons having to do with how multiprocessing in the IDE is done, clicks away from the menu and keystrokes are not seen by the menu, so this example menu cannot be dismissed -- you must follow it through to a choice. In the example below, things are set up so the menu can be dismissed and keystrokes can be used to choose items. Here we are only interested in showing what the choices are in the cascade of menus displayed.
In our choices, we have three initial characters, J, S, and W, so there are three choices in the initial menu. Each new menu will have as many choices as there are different characters in the position of the remaining choices at the position where they start to differ.
The choices are Jones, Smit..., and W.... Jones has no ellipsis (...) because there is only one choice beginning with J so if you select it, you get it. the other two have ellipses because there are multiple choices. The ellipsis starts where the characters diverge (after Smit or after W). We select W... and this new menu is displayed:
Now the choices are Watson and Wil.... If you choose Watson, that object is returned. If you choose Wil..., you get a final menu with choices Williams and Wilson (not illustrated).
So, a pop-up menu will be shown for each character position for which there remain multiple choices that have different characters at that position. When there is a single remaining choice for a character at the current character position, then that choice will appear on the menu and the user may select it directly. When there are multiple remaining choices for a particular next character, then the menu-item for that character will show just the character followed by an ellipsis, and selecting that menu-item will show a further pop-up menu for the remaining choices that have the selected character at that position.
The keyboard shortcut on each menu will be the unique character at the current character position that either selects a final choice or presents a further menu for that character. This means that a choice can be made quickly by typing the characters of the desired choice wherever there is an ambiguity, until the choice has been fully disambiguated. Note that using the keyboard shortcuts requires a proper stream argument, as detailed below (In our simple example above, no stream argument specified so shortcuts did not work.)
choices is a list of arbitrary values from which the user may select a choice. The choices must already be sorted alphanumerically by the strings that are returned by the on-print function; otherwise the menu may be confused. One of the elements of this list is returned if the user makes a selection, or nil is returned immediately if the user cancels from any menu.
on-print is a function that returns strings that will appear in the menu. It should take a single argument, which is one of the elements of the choices list, and should return a string to represent it. The default value is princ-to-string. This function will be called many times when there are many choices, and so it is most efficient if it returns an existing string rather than consing a new one on each call. This argument could be identity if the choices are already strings.
stream is either the screen or else a window that will serve as the owner of the pop-up menus. On the Windows platform (and perhaps elsewhere in the future), the keyboard shortcuts for the menu items will work only if this argument is a window that was created in the process that is calling pop-up-menus-for-many-sorted-choices. The default is the screen, and so the keyboard shortcuts would never work unless this argument is passed.
position is the position relative to the upper-left interior corner of the window (or screen) at which the upper-left corner of the pop-up menus will appear. The default is the current position of the mouse cursor.x Successive menus will always appear at the same position as the first one, rather than defaulting again to the new mouse cursor position.
case-insensitive should be a boolean value that indicates whether the choices (after the on-print function has converted them to the strings to be presented) are sorted in a case-insensitve way. The choices will then be separated into multiple menus accordingly. The default is nil, meaning a case-sensitive order.
on-help, if specified, should be a funcallable object (a function object or function name) or nil. The default is nil. A function may be used for displaying status bar messages as the user highlights individual menu items. The function should take a single argument, which will be one of the values in the choices list, and it should return a string that can be displayed in a status bar. The strings will be displayed in the status bar of the specified stream, if it has a status bar, or else in the status bar of the first ancestor window of that stream that has a status bar, if any.
Below is a complete example that uses an owner window so that keyboard shortcuts will work. The user's most recent choice is displayed in the window. Methods are defined on a window subclass so that the initial menu may be shown either by right-clicking the window or by pressing the spacebar when the window is selected. The mouse or keyboard may then be used to select choices.
The short list of choices is (:apple :blueberry :cherry :chocolate :cranberry). There is only one choice that begins with "a", so "apple" appears on the initial menu and may be chosen immediately. Likewise with "blueberry" for "b". But there are multiple choices beginning with "c", and so the third menu item will show "c ...", and choosing that item will show a second menu of all choices that being with "c". If "c" is chosen, then the second menu will show "ch ..." for the two remaining choices that begin with "ch", followed by "cranberry" since it is the only remaining choice that begins with "cr".
When using the keyboard to select choices most quickly, :apple could be selected by pressing the spacebar to show the first menu, and then pressing the "a" key. :cranberry can be selected by typing space, c, r, while :chocolate requires space, c, h, o.
(defclass menu-test-window (frame-window)
((current-food :accessor current-food
:initform nil)))
(defun select-a-food (window cursor-position)
(let* ((choice (pop-up-menus-for-many-sorted-choices
'(:apple :blueberry :cherry :chocolate :cranberry)
:stream window
:position cursor-position)))
(when choice
(setf (current-food window) choice)
(invalidate window))))
(defmethod redisplay-window ((window menu-test-window) &optional box)
(declare (ignore box))
(clear-page window)
(let* ((food (current-food window)))
(when food
(with-font (window (make-font-ex nil "Arial" 24 '(:bold)))
(draw-string-in-box window (princ-to-string food) nil nil
(visible-box window) :center :center)))))
(defmethod mouse-right-down ((window menu-test-window)
mouse-buttons cursor-position )
(declare (ignore mouse-buttons))
(select-a-food window cursor-position))
(defmethod virtual-key-down ((window menu-test-window)
mouse-buttons key-code)
(declare (ignore mouse-buttons))
(case key-code
(#.vk-space (select-a-food window #.(make-position 0 0)))
(t (call-next-method))))
(make-window :menu-sequence-test
:class 'menu-test-window
:title "Right-Click or Space"
:exterior (make-box-relative 200 200 300 200))Function, cg package
Arguments: window-or-screen title prompt icon button1 &optional button2 button3 button4 &key topmost (initial-focus :default)
This function displays a dialog box with contents described next. At least one and as many as four buttons will appear on the dialog box. The system will wait until the user clicks on a button or hits ESC or ENTER. The number of the button clicked on is returned. Hitting ENTER is the same as choosing the button1 (so 1 is returned). Hitting ESC is the same as choosing the last true button.
window-or-screen must be either a window, the screen, or nil. If nil, then the stream returned by selected-window-or-screen will be used. If the value is a visible window, the dialog will then be modal. When window-or-screen is the screen, you might want to specify the topmost keyword argument true (be sure to give values for the three optional arguments, using nil if you do not want buttons to appear). The dialog will not be modal. topmost true insures it remains visible.
title should be a string or nil. icon should be an icon (see cg-icons.html) or nil. prompt should be a string or nil. In each case, the value nil means the item is not displayed.
Each button argument should be a list, a string or nil. The string will be displayed within the button so it should be short. "OK" and "Cancel" are typical values. The value nil indicates the button should not be displayed. At least one button argument should be true.
If the value is a list, it should have two elements: a symbol or string that will appear in the button and a string, which should be a help message for the choice.
The length of prompt determines how it is displayed. A multi-line-editable-text widget (with a vertical scroll bar if necessary) is used when message is too big to fit into a static-text widget.
When topmost is true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application.
The initial-focus argument is passed to pop-up-modal-dialog to initially focus on a particular widget. Its possible values for this dialog are :default (for the leftmost button), :cancel (for the rightmost button), or :button1, :button2, :button3, or :button4 (for a button numbered from the left end), or :text for the widget that holds the message. If the specified button is not currently included on the dialog, then the nearest one is used instead. The default value is :default.
The position of the dialog when displayed is controlled by position-utility-dialog.
To display a message window without waiting for an interactive response from the user, see with-message-window.
Generic Function, cg package
Arguments: dialog &key stream initial-focus bring-thread-to-front
Exposes and selects a dialog in a modal way, where the user must interact with and exit that dialog before proceeding with anything else.
Specifically, the modal dialog will be displayed indefinitely until some user action causes the call to pop-up-modal-dialog to return.
While the modal dialog is present, all mouse events are disabled on stream as well as on all of the child and owned windows of stream (except for the modal dialog itself). And no windows are disabled if stream is the screen, or if the value of *modal-dialogs-disable-owner* is nil. This is done to force the user to complete a response to the modal dialog before continuing to interact with the rest of the application. The dialog can be said to be "modal with respect to stream ". Typically stream should be a top-level window, to establish modality with respect to its whole window hierarchy. stream can be the screen, which is the value returned by (screen *system*). See screen and *system*. stream defaults to the uppermost parent of the modal dialog, as returned by calling top-level-window on the dialog.
If an application includes multiple top-level windows and it is unsatisfactory for modal dialogs to be modal with respect to only one of the top-level windows, then an invisible window can be added to the application that serves as the owner of all of the top-level windows, and that invisible owner window can be passed as the stream argument to pop-up-modal-dialog to achieve modality with respect to the entire set of the top-level windows. To make an invisible window, simply call make-window, passing :state :shrunk as one of the initargs. To create a top-level owned window on the invisible window, call make-window again, passing the invisible window as the :owner initarg and passing the :child-p initarg as nil (which makes an owned window rather than a child window).
initial-focus may be one of the controls on the dialog, in which case that control will have the keyboard focus when the dialog appears. (This parameter exists because it does not work to call set-focus on the control before the dialog is exposed, and it is too late to call set-focus once pop-up-modal-dialog has been called to expose the dialog.) The value of this argument may be the widget object or the widget name. See the example below where the name is used.
If bring-thread-to-front is true, then set-foreground-window is called on the dialog to bring its application to the front if it was not in front already. This may be useful for a particularly important modal dialog to ensure that the user sees it. This call to set-foreground-window is always done if the owner of the dialog is the screen.
A call to pop-up-modal-dialog will return only in these cases:
The value of a control is changed by the user, resulting in the on-change event-handler for the control returning a true second value. The control is returned from pop-up-modal-dialog.
flag-modal-completion is called on the dialog. The optional value argument to flag-modal-completion is returned from pop-up-modal-dialog.
The user clicks a default-button or a cancel-button on the dialog, and the button has its default on-change event handler of return-t-from-pop-up-dialog or return-nil-from-pop-up-dialog. (Each of these functions actually just calls flag-modal-completion, returning t and nil respectively.)
user-close is called on the dialog. (This happens when the user interactively closes the window in one of the built-in ways such as by clicking the close icon on the dialog's frame or pressing alt-F4.) In this case, pop-up-modal-dialog may still not exit if there is a cancel-button on the dialog whose on-change event handler fails to exit the call by one of the other means. This functionality is implemented as a user-close :around method on basic-pane; this method generally should not be overridden.
The Lisp process that called pop-up-modal-dialog throws to pop-up-dialog. The value thrown will be returned by pop-up-modal-dialog. This is a more drastic option that is not recommended unless it turns out to be necessary for some unforeseen reason.
pop-up-modal-dialog should be called only in the process that created the dialog. If called in another process, an error is signaled. If a dialog needs to be used in multiple processes, then a separate instance should be created for each process. The Common Graphics utility dialogs that are invoked by such functions as ask-user-for-choice-from-list automatically create a separate instance for each process in which they are used. The reason for this restriction is that each process maintains an indpenedent stack of currently-invoked modal windows, and so the process that is waiting in a call to pop-up-modal-dialog needs to be the same as the creation-process that handles the events in the window.
Here is a simple example that creates a modal dialog and then displays it by calling pop-up-modal-dialog. This example sets the pop-up property, which coerces certain other properties to appropriate values for modal dialogs. It also uses the fact that its default-button and cancel-button have built-in on-change functions that will call flag-modal-completion with t and nil respectively -- that causes pop-up-modal-dialog to return true if and only if the user does not cancel the dialog.
The dialog is shown twice to illustrate the fact that dismissing a modal dialog simply hides it until further use, rather than closing it.
(let* ((margin 8)
(spacing 6)
(widget-height 24)
(width 300)
(inner-width (- width (* 2 margin)))
(height (+ (* 2 margin)(* 3 widget-height)(* 2 spacing)))
(button-top (- height margin widget-height))
(button-width 60)
(dialog (make-window :modal-dialog-test
:class 'dialog
:title "Enter Two Strings"
:pop-up t
:interior (make-box-relative 100 200 width height)
:dialog-items
(list
(make-instance 'editable-text
:name :string1
:value ""
:left margin :top margin
:width inner-width :height widget-height)
(make-instance 'editable-text
:name :string2
:value ""
:left margin :top (+ margin widget-height spacing)
:width inner-width :height widget-height)
(make-instance 'default-button
:name :ok
:title "~OK"
:left margin :top button-top
:width button-width :height widget-height)
(make-instance 'cancel-button
:name :cancel
:title "~Cancel"
:left (+ margin button-width spacing)
:top button-top
:width button-width :height widget-height))))
first-answer second-answer)
(when (pop-up-modal-dialog dialog :initial-focus :string1)
(setq first-answer (list (dialog-field dialog :string1)
(dialog-field dialog :string2)))
(setf (title dialog) "Enter Two MORE Strings")
(set-dialog-fields dialog :string1 "" :string2 "")
(when (pop-up-modal-dialog dialog :initial-focus :string1)
(setq second-answer (list (dialog-field dialog :string1)
(dialog-field dialog :string2)))
(list first-answer second-answer))))Generic Function, cg package
Arguments: printer-stream &rest restarg
Printing hardcopy is supported only when running in Windows desktop mode, and the printing functions should be called only in Windows desktop mode.
Pops up the print job dialog, where the end user may specify which printer to print on and what style of printing that printer's driver should use. An application should not call this function directly, because Common Graphics calls it internally whenever a printer stream is opened. This page documents the printer-specific arguments that you would pass to open-stream or with-output-to-printer, which Common Graphics will pass along to this function.
The argument values will determine the initially-selected options on the print job dialog, unless :no-dialog-p t is passed to bypass the dialog, in which case the argument values determine the actual print style.
Note that each printer driver supports some subset of these properties, and ignores any specification of the others. When using the print job dialog, a driver will typically suppress the properties that it does not support. But when bypassing the print job dialog by passing :no-dialog-p, it may not be clear which properties are supported, and so it's probably best to pass initargs in this case only for properties such as orientation that are supported by most any printer driver.
The keyword arguments (open-stream initargs) are:
no-dialog-p: if true, then the print job dialog is not invoked as usual, and the current Windows printer is used with its current settings, except as overridden by other initargs passed here.
start: the first page to print; see the start-page property.
end: the last page to print; see the end-page property.
min-start: the smallest number that the end user is allowed to specify as the start-page on the print job dialog.
max-end: the largest number that the end user is allowed to specify as the end-page on the print job dialog.
copies: the number of copies to print; see the driver-copies and user-copies properties.
collate-p: if true, then the output should be collated; see the driver-collate-p and user-collate-p properties.
orientation: either :portrait or :landscape; see the orientation property.
scale: a scaling factor for the printer driver to use; see the scale property.
filename: may be either nil to print output to a physical printer as usual, or else a pathname or path namestring to print to a file instead. When printing is done to a file, the file will contain printer code such as PCL or PostScript, as written by the driver of the selected printer. When a path is specified, the output will go to the file even if the print-to-file-p argument is nil or if the user unchecks the Print to file check-box on the Print Job dialog; therefore it is probably best to pass either no-dialog-p or hide-print-to-file as true when passing a filename.
print-to-file-p: if true, then the Print to file check-box on the Print Job dialog will initially be checked; if nil, it will be unchecked. Some printer drivers may not support printing to a file, in which case this check-box will not appear. If filename is nil or unspecified and the user exits the Print Job dialog with the Print to file check-box checked, then the OS will ask for the path to print to, and there is no way for Lisp to know what path was specified; therefore, if you need to know what file was created then you should instead pass the desired path as the filename argument, perhaps after calling ask-user-for-new-pathname to ask the user for the path.
disable-print-to-file: if true, then the option to print to a file will be disabled (grayed) on the print job dialog.
hide-print-to-file: if true, then the option to print to a file will not appear at all on the print job dialog.
disable-page-numbers: if true, then the Page Numbers radio button and associated page range fields on the print job dialog will be unavailable (grayed).
disable-selection: if true, then the Selection radio button on the print job dialog will be unavailable.
selection-p: if true, then the Selection radio button on the print job dialog will be initially selected, rather than the All Pages radio button.
disable-copies-and-collate-if-no-driver-support: if true and the printer driver does not support printing multiple copies or collation itself, then the options for multiple copies and collation will be disabled on the print job dialog.
print-quality: the print quality to use; see the print-quality property.
paper-size: the paper size to use; see the paper-size property.
multicolor: whether to print in multicolor or monochrome on a color printer; see the multicolor property.
no-warning-p: if true, then no warning will appear if there is currently no default printer.
printer-name: a string indicating the printer on which to print. The string should be equal to one of the values in the list returned by printer-names. This option has an effect only when the no-dialog-p option is true.
driver-name: a string indicating the printer driver to use. The default is "winspool", which is normally the appropriate value. But if you know the name of an alternate driver that you would like to use, you may specify it here.
title: a string that serves as a descriptive name for the document being printed, such as "My Primary Report". This name may appear in a system dialog that lists currently queued print jobs, for example. Adobe Distller uses this string as the default filename that it presents to the user for the PDF file that it creates. (This open-stream argument is actually handled in the device-open method for printer streams, but is included here to document all printer initargs together.)
double-sided: whether to print double-sided or single-sided. If nil (or unspecified), then the printer's default setting will be used. If :no, then printing will be single-sided. If :short-edge-binding, then printing will be double-sided and oriented toward binding (or flipping) the pages along the shorter side of the paper. If :long-edge-binding (or any true value other than the ones mentioned), then printing will be double-sided and oriented toward binding along the longer side of the paper. (Since binding along the longer side is typical, it may be easier to remember to specify t for double-sided.) Note that on the print job dialog for some printer drivers this option is called "Duplex". See double-sided.
See also pop-up-printer-setup-dialog and with-printer.
Function, cg package
Printing hardcopy is supported only when running in Windows desktop mode, and the printing functions should be called only in Windows desktop mode.
Arguments: &key stream min-margins margins orientation disable-margins-p disable-orientation-p disable-paper-p disable-printer-p disable-sample-page-p
Pops up a dialog for setting default printer orientation, paper size, and margins. This is a different dialog than the one that pops up when a printer stream is opened, and is invoked in the development environment with the File | Page Setup command.
If the user cancels from the dialog, then nil is returned.
Otherwise these values are returned:
t to indicate that the user selected OK
the left margin selected on the dialog
the top margin
the right margin
the bottom margin
the orientation selected, either :portrait or :landscape
a keyword denoting the paper size selected; for a list of possible paper-size keywords, see the paper-size property
A keyword denoting the bin from which the paper is drawn. See the paper-source printer property for the possible keywords.
A string naming the port through which printing is done to the selected printer.
A string naming the selected printer itself. This name could be passed later as the value of the :printer-name initarg to open-stream, along with the :no-dialog-p initarg, to programmatically specify this particular printer for the print job (though this printer will be the default anyway unless it is changed again in the meantime).
A string naming the printer driver that is used for the selected printer. This is usually "winspool".
The margins are fixnums specifying thousands of an inch. When this function returns, the following symbols are set to these margins:
Note that drawing on a printer stream does not automatically offset the drawing by some requested margin; instead, it is offset by a physical margin of the particular printer, which is usually around a quarter of an inch. To make it easier to draw at some arbitrary margin, when a printer stream is opened it is given margins that are equivalent to the above global margin variables minus the physical margin of the printer, so that drawing something at the printer's margins will make it appear where the global margin variables indicate. See printer-physical-offset for more information.
The orientation and paper-size selected on this dialog will determine the initial values of these properties on the print job dialog the next time that it appears when a printer stream is opened. Similarly, if the print job dialog is bypassed by passing the :no-dialog-p initarg to open-stream when creating a printer stream for a print job at some later time, then the values that the user selected on this dialog will be used for the print job unless they are programmatically overridden with other initargs to open-stream.
Note that the value of some printer properties may now be nil. If a printer stream is opened using the print job dialog, then the resulting printer object will have nil as the value of any properties for which the printer driver does not support multiple options. For example, if the particular printer driver allows the user to select either :high, :medium, or :low print quality on the print job dialog, then the value of the print-quality property of the printer object will be one of those three symbols, but if the printer driver does not offer a choice of print quality, then the value of the print-quality property will be nil.
Here is more description of the arguments:
stream* may be either nil, a window, or the screen to indicate the owner of the dialog. Defaults to the stream returned by selected-window-or-screen. If a window, the dialog will be modal with respect to the top-level window of the window, and otherwise it will not be modal. The screen is the value returned by (screen *system*). See screen and *system*.
min-margins and margins: these may be either nil or a box. The box refers to the left, top, right, and bottom margins of the printed page, measured in thousandths of an inch, where each margin is measured as a distance from that edge of the paper.
min-margins specifies the minimum margins that the user will be allowed to enter in the dialog. If a smaller margin is entered by the user, it will be replaced with the corresponding minimum value. If min-margins is nil, then some hardwired minimum will be used (which appears to approximate the physical margin limits of the printer).
margins specifies the margins that will be initially displayed on the dialog. If nil, the initially displayed margins will be the values of default-printer-left-margin, default-printer-top-margin, default-printer-right-margin, and default-printer-bottom-margin.
orientation may be nil, :portrait, or :landscape, and specifies the initially-selected orientation on the dialog. If nil, the current orientation of the printer is used.
disable-margins-p may be true or nil. If true, then the controls for specifying the margins will be disabled (grayed out) on the dialog.
disable-orientation-p may be true or nil. If true, then the radio-buttons for specifying the orientation will be disabled (grayed out) on the dialog.
disable-paper-p may be true or nil. If true, then the controls for specifying the paper source and size will be disabled (grayed out) on the dialog.
disable-printer-p may be true or nil. If true, then the button for specifying the default printer will be disabled (grayed out) on the dialog.
disable-sample-page-p may be true or nil. If true, then the image of a printed page that appears on the dialog will be blank.
See also pop-up-printer-job-dialog.
Function, cg package
Arguments: window-or-screen initial-find-string initial-replace-string search-backwards-p match-exactly-p &key (allow-replace-all t) (allow-match-exactly t) (allow-search-backwards t)
Displays a modal dialog asking the user to specify a search string and a replacement string, plus a few options for doing the search and replace. This function does not do an actual search or replace, and instead simply returns the values specified by the user in the dialog. It is then up to the application to perform a search and replace in some application-defined way.
window-or-screen is typically the window in which the search will be done, though it can actually be an arbitrary window or nil. If nil, then the stream returned by selected-window-or-screen is used. It is used in two ways: (1) The modal dialog is positioned with respect to this window according to the usual internal call to position-utility-dialog, and (2) the top-level-window of window will be passed as the stream argument to pop-up-modal-dialog, to disable user gestures on that window and all of its other owned windows while the modal dialog is present.
initial-find-string should be a string to be displayed in the search-string widget when the dialog appears. Use the null string to cause the widget initially to be empty.
initial-replace-string should be a string to be displayed in the replacement-string widget when the dialog appears. Use the null string to cause the widget initially to be empty.
search-backwards-p determines whether the check-box on the dialog for requesting a backward search will be initially checked. If true, then the widget will be checked, and if nil it will not be.
match-exactly-p determines whether the check-box on the dialog for requesting an "exact match" will be initially checked. If true, then the widget will be checked, and if nil it will not be. This option is typically used to specify whether the search will be case-sensitive or case-insensitive.
allow-replace-all determines whether the button on the dialog for requesting that all search matches be replaced will be available so that the user may press it to exit the dialog. If true, then it will be available; if nil, then it will not be. (This button is an option for exiting the dialog, as an alternative to pressing the "Replace" button to request replacing a single match.)
allow-match-exactly determines whether the check-box on the dialog for requesting an "exact match" will be available so that the user may change its value. If true, then it will be available; if nil, then it will not be.
allow-search-backwards determines whether the check-box on the dialog for requesting a backward search will be available. If true, then it will be available; if nil, then it will not be.
Five values are returned when the user exits the dialog. If the user cancels the dialog, then the first four values will be nil, and the fifth value will be the keyword :cancel. Otherwise the values are (1) the string in the search-string widget, (2) the string in the replacement-string widget, (3) the value of the search-backwards check-box (true or nil), (4) the value of the match-exactly check-box (true or nil), and (5) the name of the button that was pressed by the user to exit the dialog. If the fifth value is the keyword :replace-all, then the user has requested that all matches of the search-string be replaced; otherwise the user has requested that a single match be replaced.
Generic Function, cg package
Arguments: window
Pops up a menu for window if the shortcut-commands method for window returns a list of menu-items. Does nothing if shortcut-commands instead returns nil, which is the default case.
The default mouse-right-down methods for basic-pane and dialog-item call this function on the window that was clicked. (If a dialog-item is right-clicked, window will be the window of the dialog-item rather than the dialog-item itself.) The default virtual-key-down method for basic-pane calls this function as well when the "context menu key" is pressed (see vk-applications).
Compatibility note: in releases through 6.1, the default mouse-right-down methods called pop-up-shortcut-menu only in the IDE, and not in generated standalone applications. Now, as said above, mouse-right-down calls pop-up-shortcut-menu is both cases. This might change the default behavior of an application only if the application defined shortcut-commands methods.
This function creates (and later closes) a menu which is an instance of the class returned by the shortcut-menu-class method for window. By default, this is the shortcut-menu class, whose on-click function is default-menu-on-click. So in the default case, the value of each menu-item should be as described under default-menu-on-click. Alternately, a shortcut-menu-class method could be defined that uses a different on-click function.
Function, cg package
Arguments: window-or-screen title prompt icon string button1 button2 &key cursor-at-end
Displays a modal dialog that prompts for one modifiable string. Returns three values. The first is the modified string, the second is nil and the third is the button number.
window-or-screen is the window with respect to which the dialog will be modal (no windows are disabled if the value is the screen). If nil, the stream returned by selected-window-or-screen will be used. title is a string to display in the title-bar of the dialog. prompt is a string to display in the body of the dialog, typically describing what the user should enter in the editable-text widget just below it.
icon is the handle of an icon to display in the dialog. Typically this is the value of one of the symbols information-icon, question-icon, warning-icon, or error-icon, but may alternately be an icon handle returned by extract-icon-from-file.
string is the string to initially display in the editable-text widget where the user enters a string. The whole string will initially be selected so that the user can easily replace it by simply typing.
button1 is a string to display on the leftmost button at the bottom of the dialog. If the user presses this button or presses the Enter key, then the third return value will be the number 1. A tilde character (~) may be included in the string to underline the next character, so that the user may press the button by holding down the Alt key and pressing the key for that character.
button2 is a string to display on the rightmost button at the bottom of the dialog. If the user presses this button or presses the Escape key, then the third return value will be the number 2. A tilde character (~) may be included in the string as with button1.
If cursor-at-end is true, then the text cursor will initially be at the end of the initial string, to facilitate extending the suggested string. If nil, then the entire string will initially be selected, to facilitate replacing the string.
The position of the dialog when displayed is controlled by position-utility-dialog.
See also pop-up-strings-dialog and ask-user-for-string.
(pop-up-string-dialog (or (selected-window (screen *system*))
(screen *system*))
"Answer Box"
"Give me one good reason why I should go away."
question-icon "initial answer"
"~OK" "~Cancel")A typical usage of the returned strings would be to pass them to string-search.
Function, cg package
Arguments: window-or-screen title prompt1 icon string1 button1 button2 prompt2 string2
Displays a modal dialog that prompts for two modifiable strings. Returns three values. The first two are the modified strings, the third is the button number.
window-or-screen is the window with respect to which the dialog will be modal (no windows are disabled if the value is the screen). If nil, the stream returned by selected-window-or-screen will be used. title is a string to display in the title-bar of the dialog. prompt1 is a string to display in the body of the dialog, typically describing what the user should enter in the editable-text widget just below it.
icon is the handle of an icon to display in the dialog. Typically this is the value of one of the symbols information-icon, question-icon, warning-icon, or error-icon, but may alternately be an icon handle returned by extract-icon-from-file.
string1 is the string to initially display in the editable-text widget where the user enters a string. The whole string will initially be selected so that the user can easily replace it by simply typing.
button1 is a string to display on the leftmost button at the bottom of the dialog. If the user presses this button or presses the Enter key, then the third return value will be the number 1. A tilde character (~) may be included in the string to underline the next character, so that the user may press the button by holding down the Alt key and pressing the key for that character.
button2 is a string to display on the rightmost button at the bottom of the dialog. If the user presses this button or presses the Escape key, then the third return value will be the number 2. A tilde character (~) may be included in the string as with button1.
prompt2 is a string to display in the dialog above the lower editable-text widget.
string2 is the string to initially display in the lower editable-text widget where the user enters a second string.
The position of the dialog when displayed is controlled by position-utility-dialog.
See also pop-up-string-dialog and ask-user-for-string.
(pop-up-strings-dialog
(or (selected-window (screen *system*))
(screen *system*))
"Answer Box"
#.(format nil "Enter a string to remove, followed by a string ~
to substitute in its place.")
question-icon "initial string to remove" "~OK" "~Cancel"
"Replacement string:" "initial replacement string")A typical usage of the returned strings would be to pass them to string-replace.
Function, cg package
Arguments: position1 position2
Returns a position object whose components are
(+ (position-x position1) (position-x position2)) and
(+ (position-y position1) (position-y position2))Contrast with nposition+, which modifies position1 rather than creating a new position object. (See position-x and position-y.)
Function, cg package
Arguments: position1 position2
Returns a position object whose components are
(- (position-x position1) (position-x position2))and
(- (position-y position1) (position-y position2))Contrast with nposition- which modifies position1 rather than creating a new position object. (See position-x and position-y.)
Function, cg package
Arguments: position
Returns:
(sqrt (+ (square (position-x position))
(square (position-y position))))This is the Euclidean length of the two-dimensional vector represented by position. (allegro:square squares its argument). (See position-x and position-y.)
Function, cg package
Arguments: text-edit-pane index &key bottom position-to-return
Returns the pixel position of the character at index in text-edit-pane.
The returned position object is in stream coordinates, meaning that it is measured from the upper-left corner of the scrollable contents of the window, and so the value will not be affected by the current scroll-position of the window.
text-edit-pane should be a text-edit-pane or rich-edit-pane.
index should be a non-negative integer indicating a character, where 0 indicates the first character in the window, (file-position text-edit-pane) indicates the character immediately to the right of the text cursor, and (file-length text-edit-pane) indicates the hypothetical character just after the last character. (See file-position and file-length.)
If bottom is nil, as it is by default, then the returned position is of the upper-left corner of the character cell. If bottom is true, then it is the lower-left corner instead.
If position-to-return is nil, as it is by default, then a new position object is consed and returned. Otherwise position-to-return may be a position object, in which case it is filled in and returned in order to avoid consing a position object.
For a text-edit-pane with a fixed-width font, the returned value could alternately be derived by calling such functions as line-height, line-number-from-char, and char-from-line-number. So this function is most useful for a rich-edit-pane, which typically has differing line heights and character widths.
See also character-index-at-position.
This example would return the pixel position of the bottom-right corner of the very last character's character cell:
(position-of-character-index
my-text-edit-pane (file-length my-text-edit-pane)
:bottom t)Function, cg package
Arguments: position theta
Returns a position which is the argument position rotated by theta degrees counterclockwise about the origin.
Function, cg package
Arguments: position matrix
Transforms the given position with the supplied matrix, which is a 2 by 2 array (or larger 2-dimensional array -- extra cells of the array are ignored). Even if the elements of matrix are floats, the returned position will have rounded whole number components. The transform works as follows:
xnew = A(0,0)*xold + A(0,1)*yold
ynew = A(1,0)*xold + A(1,1)*yoldFor example:
(setq ar (make-array '(2 2)
:initial-contents '((5.0 2.0) (3.0 1.0))))
(setq p1 (make-position 7 10))
(position-transform p1 ar)
**returns**
#.(make-position 55 31) ; = 5*7 + 2*10, 3*7 + 1*10Generic Function, cg package
Arguments: owner dialog return-position
This generic function is called internally when one of the following Common Graphics functions is called. They all invoke a utility dialog written in Lisp.
pop-up-message-dialog, ask-user-for-choice, ask-user-for-choice-from-list, ask-user-for-string, pop-up-string-dialog, pop-up-strings-dialog, y-or-n-dialog, yes-no-or-cancel-list, ask-save-changes.
The default method is shown below. It calls center-modal-children. Programmers may override the default if desired.
The owner argument is the window or screen that was passed as the value of the stream argument to the utility function to serve as the owner of the dialog. The dialog argument is the dialog that is being invoked. The return-position argument is a position that the method should modify and return (or it may return another position object). The dialog will then be positioned with its upper-left corner at this returned position. The position should be in screen coordinates.
This function is not called for Common Dialogs since there is no Common Graphics window object to position. The only way to position a Common Dialog is to move the owner window before invoking the dialog; the Common Dialog will then typically appear with its upper left corner at or near the upper left corner of the owner window that is passed to the utility dialog function. (See center-all-modal-dialogs-on-screen.)
Here is the default method. An application could add a method to override this default in order to position the Common Graphics utility dialogs in some arbitrary way. When this function is called, the dialog already has the width and height at which it will appear, so the method can use that information to position the dialog.
(defmethod position-utility-dialog ((owner t)(dialog t) return-position)
;; A user-overridable generic function. Should modify
;; return-position to contain the screen position for the dialog
;; and return it the position
(let* ((exterior (exterior dialog))
(width (width exterior))
(height (height exterior))
(owner-box (interior owner)))
(case (center-modal-children owner)
(:on-owner
(window-to-screen-units owner
(nmake-position return-position
(floor (- (box-width owner-box) width) 2)
(floor (- (box-height owner-box) height) 2))))
((nil)
(let* ((margin (modal-dialog-margin (configuration *system*))))
(window-to-screen-units owner
(nmake-position return-position margin margin))))
(t (let* ((box (center-box-on-screen width height)))
(nmake-position return-position
(box-left box)(box-top box)))))))Function, cg package
Arguments: pos
Returns the x component of the argument position.
The function is setf'able, with the setf function being #'(setf position-x) with arguments (x position). Thus:
cg-user(4): (setq p1 (make-position 10 20))
#<position 10 20>
cg-user(5): (position-x p1)
10
cg-user(6): (setf (position-x p1) 11)
11
cg-user(7): p1
#<position 11 20>
cg-user(8): (apply #'(setf position-x) (list 12 p1))
12
cg-user(9): p1
#<position 12 20>
cg-user(10): See also position-y and make-position.
Function, cg package
Arguments: pos
Returns the y component of the argument position.
The function is setf'able, with the setf function being #'(setf position-y) with arguments (y position). Thus:
cg-user(4): (setq p1 (make-position 10 20))
#<position 10 20>
cg-user(5): (position-y p1)
20
cg-user(6): (setf (position-y p1) 30)
30
cg-user(7): p1
#<position 10 30>
cg-user(8): (apply #'(setf position-y) (list 40 p1))
40
cg-user(9): p1
#<position 10 40>
cg-user(10): See also position-x and make-position.
Generic Function, cg package
Arguments: other
Returns t if the argument is a position object and returns nil if it is not. See make-position.
positionp should not be called on objects created by the macros with-positions and with-positions-and-boxes. The return value of this function is undefined for objects created by the macros because type information for such objects is sacrificed to achieve the non-consing efficiency of stack allocation.
Function, cg package
Arguments: position1 position2
Returns true if its two arguments, which must be position objects, have equal x and y components. Returns nil if they are different.
Function, cg package
Arguments: position scale-x scale-y
Returns a position whose x component is (position-x position) times scale-x and rounded and whose y position is (position-y position) times scale-y and rounded. (See position-x and position-y.)
Function, cg package
Arguments: function &key arguments (process mp:*current-process*) type delete-types unless-types
This function places a funcallable object to be called later onto a "funcall queue" for the specified Common Graphics process. The function call will be made only after all pending window messages in that process have been handled completely, and after all function calls that were already in the funcall queue for that process have been called and have returned.
The queued funcalls are called by the main event-handling loop inside the function event-loop, which is normally called by any Common Graphics process. If that process is currently idle, then its event loop will handle the posted funcalls quickly. In CG/JS mode they will also be called by cg-process-wait and process-pending-events.
This function can be called whenever you need to call a CG function in a process other than the *current-process*. For maximum safety, any CG function that's called on a window (see basic-pane), the screen, or a menu generally should be called in the creation-process of that object. One reason apparently is that the call may generate messages from the web browser (in CG/JS mode) or the underlying window system, and those messages are always handled in the creation-process. When everything is done in the creation-process, those messages will not be handled until the function call returns and the process returns to its event-loop that will then handle the new messages. But if the function is called in some other process, then the creation-process could receive and handle the messages before the function call returns, which is generally not expected and could lead to confusion in certain cases.
That is not a concern in a typical application, because CG code is generally initiated by a user gesture on a window or menu and so is already running in the creation-process of the windows on which that code will call CG functions. But this function exists for atypical cases.
Here is a simple example that ensures that a call to resize-window on my-window will happen in the creation-process of that window:
(let* ((creation-process (creation-process my-window))
(pos (make-position 200 300)))
(cond ((eq mp:*current-process* creation-process)
(resize-window my-window pos))
(t
(post-funcall-in-cg-process 'resize-window
:process creation-process
:arguments (list my-window pos)))))Here are the arguments to this function:
function must be a funcallable object (a function name or function object). The function will be called later when the posted funcalls are processed. The function will be passed the arguments that are in the list passed as the arguments argument, if any.
arguments: the value of this keyword argument should be a list of arguments to pass to function. An alternative to passing an argument list here is to pass the function argument as a closure that takes no arguments but instead closes over any variables that need to be passed. A closure form may be more elegant, but note that the closed-over variables will be evaluated later when the function is called, rather than when it is posted. Passing an argument list instead will evaluate the forms that produce the arguments at posting time.
process: the value of this keyword argument should be the process that should call the function. It defaults to the *current-process*. The queued function will later be called inside the process' main message-handling loop inside the function event-loop; therefore, the process argument should always be a Common Graphics process. (A Common Graphics process should always call event-loop; see About using multiple windowing threads in a Common Graphics application in cgide.html.)
type: the value of this keyword argument, if it is specified, should be an arbitrary symbol to classify this queued funcall. For example, if you are showing a message when the mouse enters a widget, you might want to pass :mouse-in-message to indicate that this is a queued funcall for a mouse-in message. This value may be used by subsequent queued funcalls that specify delete-types or unless-types arguments. (This argument is not otherwise used.)
delete-types: the value of this keyword argument, if it is specified, should be a list of symbols that may have been passed as the value of the type argument to earlier calls. Any currently queued funcalls of those types will be deleted from the queue when this function call is placed there. As an example, if you are now showing a status-bar message when the mouse enters a widget, for efficiency you may want to remove any currently queued funcalls for status-bar messages, since they would get overwritten immediately anyway.
unless-types: the value of this keyword argument, if it is specified, should be a list of symbols that may have been passed as the value of the type argument to earlier calls. If there are any currently queued funcalls of any of those types, then this funcall will not be added to the queue. This could be useful for determining that a currently queued call is already going to handle whatever this funcall was going to handle, and so there is no need to queue this one in addition.
Note that the queued functions are always called asynchronously, and so the caller of post-funcall-in-cg-process cannot wait for a returned value or an indication that the code has run. So it is probably most useful to call post-funcall-in-cg-process at the very top of a message-handling method or function, so that everything that would have been done by the event-handler is done instead by the queued function call. (ide:eval-in-listener-thread, on the other hand, can wait for completion, though it may be used only in the IDE and not in a standalone application.)
About design considerations for event-driven applications in cgide.html for more information.
Below is an example that causes each mouse-in event of a window to print a string to the Debug Window (when the example is run in the IDE) and then to wait two seconds. Because this action is queued by calling post-funcall-in-cg-process each time, the messages will not print more often then every two seconds, even if you rapidly move the mouse into and out of the window, because each queued function will be called only after the preceding one has returned. (Without the call to post-funcall-in-cg-process, the call to sleep would cause further messages to be handled, and each string would be printed almost immediately when the event occurs.)
Notice that the mouse-moved method continues to print coordinates immediately to the IDE status-bar, even as the printing done by the mouse-in method is delayed by the calls to sleep. (In real application code, the delay would more likely be done by a call to mp:process-wait or with-process-lock rather than a call to sleep like the one in this simple example.)
(in-package :cg-user)
(defclass my-win (frame-window)())
(defmethod mouse-moved ((window my-win) buttons pos)
(declare (ignore buttons))
(setq pos (copy-position pos))
(ide:lisp-message "Mouse now at ~a ~a"
(position-x pos)(position-y pos)))
(defmethod mouse-in ((window my-win) buttons mouse-out-object)
(declare (ignore buttons))
(post-funcall-in-cg-process
(lambda ()
(format t "~&Moved out of ~a into ~a~%"
(name-string mouse-out-object)
(name-string window))
(sleep 2))
:type :mouse-in-message)
#|
;; This alternative uses an :arguments argument
;; rather than closing over variable bindings. Note that this
;; causes the format arguments to be evaluated when this code
;; is posted rather than when it is run later.
(post-funcall-in-cg-process
(lambda (format-string &rest format-args)
(apply #'format t format-string format-args)
(sleep 2))
:arguments (list "~&Moved out of ~a into ~a~%"
(name-string mouse-out-object)
(name-string window))
:type :mouse-in-message
;; Adding this would prune out mouse-in messages that are
;; still queued when this later event is handled, so that only
;; one mouse-in message will print after the last mouse-in event.
:delete-types '(:mouse-in-message))
|#
)
(make-window :my-win :class 'my-win)Generic Function, cg package
Arguments: configuration
Specifies that Lisp forms beginning with particular symbols should be pretty-printed with each pair of elements on an individual line, after a specified number of initial elements. This is done only if the pprint-plist-pairs-on-separate-lines option is true.
The value is a list where each member is a list of a symbol and an integer for the number of initial elements for forms beginning with that symbol. The initial value is similar to this:
((open-menu 4)(make-texture-info 1)(make-instance 2)(make-window 2))This causes the pretty printer to print a make-window form, for example, with each initarg and value on its own line, like this:
(make-window :my-window
:class 'frame-window
:exterior (make-box 200 100 500 400)
:scrollbars t
... )One place that this feature is used internally is when generating the source code for recreating a form window in an IDE project, which is saved in a
Generic Function, cg package
Arguments: configuration
This configuration option determines whether Lisp forms beginning with particular symbols should be pretty-printed with pairs of elements on individual lines, as specified by the pprint-plist-definers option. The initial value is nil. See pprint-plist-definers for more information.
Generic Function, cg package
Arguments: dialog-item
The value returned by the generic function can be nil, t, or a plist (a list of conses). The setf of this function may be called to change the pressed colors of a dialog-item at any time. The value controls how the appearance of a picture-button or multi-picture-button control changes when pressed.
If the value of this property is nil, then no color change occurs when the button is pressed.
If the value is a plist, then the first element of the conses in the plist is the color before pressing, and the second element is the color after pressing. The after pressing colors replace the before pressing colors while the button is pressed. For example, the following form will return the default pressed-color-mapper, which would cause a pressed picture-button to display white pixels where it normally displays light-gray pixels and so on.
(list (cons light-gray white)
(cons gray light-gray)
(cons dark-gray gray))Alternately, the value of this property may simply be the symbol t to "reverse" all of the colors of the pixmap when the button is pressed. This option effectively draws the pixmap such that every bit in each pixel value is reversed. The effect of this depends on the nature of the pixmap. For a true-color pixmap, where the pixel value denotes a color directly, this will always result in the hue that would be on the opposite side of a color wheel, and an opposite lightness as well; so a dark red, for example, would become a light cyan. For a non-true-color pixmap, where the pixel value is an index into a vector of colors, this will select the color that happens to be at the "opposite position" in the color vector (as if the order of all of the colors were reversed). The colors in the default-pixmap-color-vector are arranged with opposite colors at opposite positions, and so any pixmap that uses this particular color vector as the value of its colors property will reverse all of its colors just as a true-color pixmap would.
pressed-color-mapper is a property of the multi-picture-button and picture-button classes.
Generic Function, cg package
Arguments: section
Returns the section in a grid-widget previous to the argument section.
Function, cg package
Arguments: section subsection &optional count
Returns the previous subsection in the given section before the given subsection, and the index within that subsection as a second value. If the first subsection is passed in, then nil is returned.
Generic Function, cg package
Arguments: class-or-class-name
Returns the name of one of the slots of the specified class, which will be used to print instances of the class in a meaningful way in class-grid widgets and object-editor dialogs. The value may be set at any time by calling (setf primary-name-slot).
class-or-class-name should be either a class object or the name of a class.
If a secondary-name-slot has also been established for this class, then the values from the two slots will be printed together with a comma and space in between, as in:
"primary-slot-value, secondary-slot-value".These slots are used whenever a class instance is displayed in a cell of a class-grid, or in a widget on an object-editor, or in a built-in pop-up menu of an object-editor. At those times, primary-name-slot is called on the class. If a slot name (rather than nil) is returned, then a string is derived from the value of this slot and the value of the secondary-name-slot, if any. Otherwise the class instance will be printed using its print-object method, as usual.
These slot values are also used internally to cache a sorted list of the edited-instances of an object-editor dialog. That allows browsing the instances in an intuitive order, and allows the object-editor-select facility to handle a large number of choices as a series of pop-up menus.
This facility may be useful for a couple of different reasons:
It may be desirable for the user interface to present a "pretty name" that is different than a print-object string that's more useful to developers.
The IDE's Class Interface Editor dialog (where these slots can be specified) can be used to create browsers of database classes without writing any code, not even a print-object method.
Generic Function, cg package
Arguments: printer-stream code
Print-abort-proc is called automatically by the system whenever the user aborts a print job that is in the process of being printed. The built-in primary method in the development environment (but not in a runtime application) on printer (the usual class of the argument printer-stream) simply pops up a warning dialog with an appropriate message. An application may add a print-abort-proc method as a hook into aborted print jobs, in order to implement some desired side effect. The printer-stream argument is the printer stream, and the code argument is the integer that the operating system passes to identify the particular type of abort.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
Arguments: printer
Returns the print-quality value for the argument printer.
Possible values are :high, :medium, :low, and :draft (in order of decreasing quality) or an integer denoting the number of pixels per inch.
A lower quality may print more quickly.
print-quality is a property of the printer class.
This generic function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream using the :print-quality initarg. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
Arguments: rich-edit-pane printer-stream &key (start 0) (end :end) (left (left-margin printer-stream t)) (top (top-margin printer-stream t)) (right (right-margin printer-stream t)) (bottom (bottom-margin printer-stream t))
Prints all or part of the text of rich-edit-pane (which must be an instance of the rich-edit-pane class) to printer-stream.
start and end specify the range of characters of the rich-edit-pane to print, and default to the full text of the rich-edit-pane. end is generally an integer like start, but can also be :end (the default) to indicate the end of the text.
left, top, right, and bottom indicate the rectangular region of the printed page to print the text to, and are measured in pixels. These values default to the margins of the printer stream, which are established based on what the end user specified in the page setup dialog (or to half an inch, if the user has not invoked this dialog). When passing in custom values, it is best to pass in values that are added to (or subtracted from) these defaults, since the margins are internally calculated to be relative to the hard margins beyond which the printer cannot print. Also, the function stream-units-per-inch may be called on the printer stream to find the resolution of the printer. So to print text with a left margin that is two inches in from the page margin requested by the end user, you would pass the :left argument like this:
:left (+ (left-margin printer-stream t)
(* 2 (stream-units-per-inch printer-stream)))See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Function, cg package
Arguments: pathname-string &key font left-margin-in-inches right-margin-in-inches newline-spacing-in-lines just-return-text-height-p
Prints a text file located at pathname-string on a printer in a particular font, using a particular left-margin-in-inches and right-margin-in-inches. Wraps text as needed at spaces to prevent it from exceeding the right margin.
If newline-spacing-in-lines is greater than zero, then this additional amount of space will be left between lines where there is an explicit newline in the text (but not where text wraps automatically).
If just-return-text-height-p is true, then no printing is done, and instead a number is returned indicating the total vertical pixel height of all of the text. This can be used to determine the amount of space or number of pages that a particular font would require, for example.
Generic Function, cg package
Arguments: printer
Returns the name of the argument printer.
printer-name is a property of the printer class.
This generic function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Function, cg package
Arguments:
Printing hardcopy has been implemented only on Windows, and this function will return nil in CG/JS mode.
Returns a list of strings, where each string is the name of an available printer (including networked printers). When calling open-stream to open a printer stream and passing the :no-dialog-p initarg to avoid showing the print job dialog, one of these printer names may be passed as the :printer-name initarg to open-stream in order to print on that printer. (On the other hand, when the :no-dialog-p initarg is nil, passing a :printer-name initarg does not work to determine the printer that is initially displayed on the dialog.) Here is an example that prints a half-inch tall string on each available printer, where the printed string points out the name of the printer on which it is being printed.
(dolist (name (printer-names))
(format t "~&Printing to ~a.~%" name)
(with-output-to-printer (printer
:no-dialog-p t
:orientation :landscape
:printer-name name)
(setf (font printer)
(make-font-ex nil :arial
(floor (stream-units-per-inch printer)
2)))
(format printer "This is printer ~a." name)))Function, cg package
Arguments: printer-stream
Returns a position that indicates the "physical" margins outside of which a printer cannot draw. The x coordinate of the position is the device's left hardware margin, and the y coordinate is the top margin. The right and bottom margins will be the same as the left and top margins respectively.
The values are measured in the device's native pixel size, and will typically indicate a quarter of an inch. So for a laser printer whose native resolution is 600 pixels per inch, the position (150 150) would be returned if it can draw anywhere except within a quarter of an inch of the edge of the paper.
The important thing to remember is that anything that is drawn on a printer stream will be positioned relative to this hardware margin. That is, drawing something at position (0 0) will typically draw it at a quarter inch from the edge of the paper.
The recommended way to calculate the coordinate range for drawing on a printer stream is to refer to the left-margin, top-margin, right-margin, and bottom-margin properties of the stream. These values will reflect the user's requested margins (see pop-up-printer-setup-dialog), adjusted for the printer-physical-offset and measured in the stream's current stream-units-per-inch that you may have set. Drawing within the coordinate range specified by these margins will always fit the drawing within the user's requested margins.
While typically there is no need to call printer-physical-offset, it can help you understand why a printer's margin properties are not the values that you might expect.
See also printer-physical-size.
Function, cg package
Arguments: printer-stream
Returns a position that indicates the physical size of the paper on which a printer stream is drawing. The x coordinate of the position is the width of the paper, and the y coordinate is the height. The values are measured in the device's native pixel size (which could be found by calling stream-units-per-inch if you do not change that value beforehand).
To calculate the coordinates for drawing on a printer stream, it is better to use the left-margin, top-margin, right-margin, and bottom-margin properties of the stream. See printer-physical-offset for a more complete explanation.
Generic Function, cg package
Arguments: printer
Returns a string such as "LPT1:" that names the port to which a printer stream will print. If the printer stream is printing to a file rather than a printer (as when the user selects the "Print to File" check-box on the Print Job dialog), then the port-name property of the printer stream will return nil rather than a string, and the filename property of the printer stream will return the path namestring of the file being printed to; otherwise filename returns nil and port-name returns a port-name string.
The port-name value is determined by the end user's choice of printer on the Print Job dialog that appears when a printer stream is opened, or according to the current Windows printer if the Print Job dialog is bypassed.
printer-port-name is a property of the printer class.
This generic function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream using the :port-name initarg.
Generic Function, cg package
Arguments: cg-configuration
This is an obsolete IDE configuration option that exists only for backward compatibility. It had been used by invoke-private-html-browser.
Function, cg package
Arguments:
Processes any waiting events, and any arriving during processing, then returns leaving the event queue empty. We generally recommend that you put calls to process-pending-events in any cpu-intensive loops, because doing so allows you to break out of the loop if necessary. If you execute a loop that turns out to be an infinite loop and there is no call to process-pending-events, it may not be possible to regain control and Lisp may fail.
In particular, if you have a busy loop (typically for a dragging operation) that stops looping when a function like key-is-down-p or mouse-button-state indicates a user gesture for exiting the loop, then you likely need to call this function inside the loop to handle events that are needed by those functions. This is not needed in Windows desktop mode, but is needed in CG/JS mode, so code that had run only in Windows desktop mode may need this change to also run in CG/JS mode.
For CG/JS mode, see also *use-alternate-websocket-nudge* if your custom dragging loop is not as smooth as you would like.
On the other hand, calling process-pending-events can sometimes lead to obscure bugs because it can alter the order in which events are handled in a non-deterministic way. See About design considerations for event-driven applications in cgide.html and post-funcall-in-cg-process.
Function, cg package
Arguments:
This function was specific to GTK, which is no longer supported, and so this function is no longer needed. Calling process-pending-events is now preferred everywhere.
Function, cg package
Arguments: &optional no-wait
Reads and processes a single event. This function may be useful to control the rate of event processing, or in the listen functions of some types of stream. Returns t if an event was processed, nil if not.
No-wait determines the behavior when there is not currently a pending event to process. If true, then process-single-event returns nil immediately; if nil, it waits until an event arrives.
See event-loop, which provides a loop with calls for processing events and additional functionality for managing threads. In general, you should use event-loop in preference to writing custom loops usign process-single-event.
Generic Function, cg package
Arguments: object
Returns a list of the properties (as property objects) of the argument.
Generic Function, cg package
Arguments: object name
Returns a list of choices suitable as values of the property of object named by the name argument. Returns nil if object does not have a property named by name, or there are no choices suitable for object.
Function, cg package
Arguments: object-or-class property-or-name
Returns the default value of the property on the specified class.
Generic Function, cg package
Arguments: object property-name value
Returns true if value is the default value of the property named by property-name on object.
Generic Function, cg package
Arguments: object name
In releases prior to 7.0, this generic function was called property-editor-mode. The name has changed to remove a name conflict with ide:editor-mode.
Returns one of the symbols listed below, indicating the style of extended editing that will be performed by the inspector for the property of object named by name. The extended editor is invoked by pressing the small button on the right side of the value when a property row is chosen in the inspector. This function returns one of the following values:
:long-expression: edit in a separate window.
:number: edit a number (typically an integer) in a separate window.
:multiple-choice: display the choices in a combo-box or similar control.
:toggle: switch between t and nil.
:color: display a color choice dialog.
:font: display a font choice dialog.
:path: display a dialog for choosing a directory or file.
:menu: display the menu editor. Applies only to the menu property of a frame window.
:function: the value will be a symbol naming a function (as in the event-handler properties). If the symbol names a user-supplied function, display the code for that function if possible. Otherwise display a function definition template in an editor buffer associated with the form.
For example, when running the IDE, you will typically have a Form window named :form1 (or sometimes :formN for an N bigger than one). Make a variable have that form as its value, perhaps by evaluating
(setf myform (find-window :form1))Or by choosing Tools | Get Component, then clicking on the form window (away from any control), and then evaluating (setf myform *) in the Debug Window.
Once the value of myform is the form, then here are the editor modes for several form properties:
(property-editor-type myform 'background-color) **RETURNS** :color
(property-editor-type myform 'border) **RETURNS** :multiple-choice
(property-editor-type myform 'child-p) **RETURNS** :toggle
(property-editor-type myform 'class) **RETURNS** :multiple-choice
(property-editor-type myform 'cursor) **RETURNS** :long-expression
(property-editor-type myform 'height) **RETURNS** :numberGeneric Function, cg package
Arguments: object name
Returns the help string, if there is one, of the property named by name of object.
Generic Function, cg package
Arguments: object name
Returns whether the property named property-name will not appear in the IDE's inspector when object is inspected. There is normally no need for users to call this function, but methods may be added to control behavior of the inspector.
The usual alternative is to pass the hidden initarg for the property in a defproperties form for the class of the object. Adding methods to this generic function would be needed only if some instances of the class but not others should hide this property.
Generic Function, cg package
Arguments: object name
Returns true if the property of object named by name is read-only, and returns nil otherwise. The inspector does not allow the user to modify the value of read-only properties.
Generic Function, cg package
Arguments: object name
Returns the name of the reader function for the property of object named by name. If a reader is not specified explicitly for a property, it defaults to the name of the property.
Generic Function, cg package
Arguments: object name
This function takes an object (object) and a property name (name) and returns true if the remake flag is turned on for that property of that object and returns nil if the flag is off. If the remake flag is on, object will be recreated automatically if the value of this property is modified, because that is deemed necessary to entirely effect the change. (For example, the operating system may not permit an object to be modified. In that case, the current object is destroyed and a new object with all the same properties except the one being modified preserved is created.)
Generic Function, cg package
Arguments: object name
Returns the Lisp type for the property of object named by name. The inspector will not allow the property value to be modified to a value that does not satisfy this type.
Generic Function, cg package
Arguments: object property-or-name
Returns the current value of a specified property of object. property-or-name should be either a property object or the symbol that names the property. When property-or-name is a property object, it should be one that was returned by calling properties on the same object that is now being passed to property-value. Passing the property object is more efficient than passing the property name.
To retrieve the values of particular properties when the names of the property-reader functions are known, it is more efficient to call the reader functions directly. But calling property-value may be useful for meta-level uses such as finding the values of all of the properties of an object. For example, the following function returns a list of the names and values of all of the properties of an object.
(defun list-properties (object)
(mapcar #'(lambda (property)
(list (name property)
(property-value object property)))
(properties object)))If property-or-name is a symbol but no property of object is found by that name, then an error is signaled. Otherwise the property-reader of the property is called, and the value that it returns is returned. If an error occurs in the call to the property-reader function, the error is trapped and the keyword :property-read-error is returned.
See defproperties for information on defining properties on any type of object.
Generic Function, cg package
Arguments: object name
Returns the name of the writer function for the property of object named by name. If a writer is not specified explicitly for a property, it defaults to the setf of the name of the property.
Generic Function, cg package
Arguments: grid-section-any
Returns the value of the proportional property of its argument. The default value is t for a grid-row-section or grid-column-section, and nil for a grid-row or grid-column.
This property determines whether space will be distributed among a grid-section and its siblings. When a grid-row-section or grid-column-section is resized, any grid-rows or grid-columns in that section that have their proportional property turned on are also resized proportionally to each other as needed in order to keep the section exactly filled by its set of subsections (when possible). For example, if a grid-column-section has six columns, and the two columns that are proportional have sizes (widths) of 100 and 200, and the user stretches that grid section by 30 pixels, then the two proportional columns will also stretch to become 110 and 220 pixels wide.
Similarly, when the whole grid-widget is resized, any grid-column-sections or grid-row-sections within it that have their proportional property turned on are also resized as needed in order to keep the grid exactly filled by its sections (and any of their proportional subsections are resized in turn).
It is advisable to make at least one grid-row-section and at least one grid-column-section of any grid-widget be proportional, so that the sections always fill the grid.
Typically, if a grid-section contains only one subsection, it is desirable to make that subsection be proportional so that it always fills its section.
Grid-sections that have no proportional subsections will be scrollable when the fixed sizes of the subsections exceeds the whole section size, as long as the section's scrollbars property is turned on. (It will also scroll even if it contains proportional subsections if the size of the non-proportional subsections exceeds the section size.)
proportional is a property of the grid-subsection, grid-column, row-header-column, grid-row, column-header-row, grid-section, grid-column-section, and grid-row-section classes.
Generic Function, cg package
Arguments: configuration &optional default
Returns the proportional font in configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
proportional-font is a property of the configuration class.
Generic Function, cg package
Arguments: window
Returns the window whose menu-bar will be searched when a keypress event occurs in the argument window. If a menu-item is found whose event-synonym matches the keypress event, then this menu-item is invoked instead of calling virtual-key-down as usual. Menu accessors such as Alt-F to show the File menu are also redirected according to this generic function.
Applications should not call this function, but it may be useful to add methods to it when the default method does not allow keyboard shortcuts to access the desired menu-bar. The default method returns the window itself if it has a menu-bar, and otherwise its owner if it has a menu-bar, and so on up through the top-level owner window; if no menu-bar is found, the top-level owner window is returned.
If an application has one top-level window that should be able to access a second top-level window's menu-bar, and the second window is not the owner of the first, then it may be useful to write a proxy-menu-bar-window method on the class of the first window that returns the second window. This is how the IDE allows its various top-level windows to access the single IDE menu-bar via keyboard shortcuts.
It is still the responsibility of the menu-bar commands to direct their functionality to the appropriate window. This can be done in a handle-menu-selection method or (more typically) in the on-click function of particular menus.
See cg-events.html for information about event handling in Common Graphics and see event-synonym, handle-menu-selection, and on-click.
Function, cg package
Arguments: format object &key empty-os-clipboard
Pushes object onto the clipboard and trims the clipboard to (clipboard-history-limit (configuration *system*)) items if necessary (see clipboard-history-limit, configuration, and *system*).
The new item is also placed into the Windows clipboard, ready to be pasted by other applications.
The format argument should be one of (:text :rich-text :pixmap) and should correspond to the type of object being placed onto the clipboard. Any object may be passed with the :text format, in which case the actual object is placed onto the Lisp clipboard stack for pasting within Lisp, while a string representation of the object is placed onto the Windows clipboard for pasting into other applications. When using the :rich-text format, the object must be a string which is a valid piece of rich text, and when using the :pixmap format the object must be a Common Graphics pixmap, which is placed onto the Windows clipboard using the "device-independent bitmap" format.
If a window or nil is passed as the format, the function will act as if :text were passed. (This behavior maintains backward compatibility with pre-6.0 releases where the second argument had to be a window or nil. The window was not useful as an argument, while a format argument is.)
If empty-os-clipboard is true (as it is by default), then the operating system is first cleared of objects of all clipboard formats before adding the new object. This ensures that no other objects are left on the OS clipboard with the new object. If empty-os-clipboard is nil, then only the object of the specified format is replaced on the OS clipboard.
A simpler function for dealing directly with the system clipboard (when you don't care about the Lisp clipboard stack) is clipboard-object.
See cg-clipboard.html.
Function, cg package
Arguments:
Returns a pre-defined icon to accompany a question to the user. In CG/JS mode this is actually a pixmap, which can be used as an icon in that mode. In Windows desktop mode it is the icon that is the value of the question-icon variable.
function, cg package
Arguments: point box &optional pos-to-return &key margin
Returns the point on the edge of a box where it is crossed by a line that passes through the center of the box and through an arbitrary point. Returns nil if the box center and the arbitrary point are the same.
The first argument is a position object for the arbitrary point, and the second argument is a box object. Returns a position object or nil.
If pos-to-return is nil or unspecified, then a new position object is created and returned. Otherwise pos-to-return should be a position object, which will be modified and returned.
The margin argument is somewhat obscure. If specified, it should be a real number indicating a distance. If the real intersection point is less than this distance from a corner of the box, then the returned point will be adjusted so that it is this distance from the corner. (This is used by one application to avoid drawing a connecting line to a rounded corner of a rounded box.) If you specify a value for margin, you must also specify a value for the pos-to-return optional argument. Specify nil if you do not want to specify a position.
As usual, position and box objects should contain integers. See make-position and make-box. See also radial-line-box-intersection-x-y and radial-line-circle-intersection.
function, cg package
Arguments: point-x point-y box-left box-top box-right box-bottom &key margin
Returns as multiple values the coordinates of the point on the edge of a box where it is crossed by a line that passes through the center of the box and through an arbitrary point. Returns nil if the box center and the arbitrary point are the same.
The first two arguments are real numbers for the X and Y coordinates of the arbitrary point. The remaining required arguments are real numbers that specify the sides of a box. Returns two real numbers for the X and Y coordinates of the intersection point, or nil.
The margin argument is somewhat obscure. If specified, it should be a real number indicating a distance. If the real intersection point is less than this distance from a corner of the box, then the returned point will be adjusted so that it is this distance from the corner. (This is used by one application to avoid drawing a connecting line to a rounded corner of a rounded box.)
See also radial-line-box-intersection and radial-line-circle-intersection-x-y.
function, cg package
Arguments: point circle-center radius &optional pos-to-return
Returns the point on the edge of a circle where it is crossed by a line that passes through the center of the circle and through an arbitrary point. Returns nil if the circle center and the arbitrary point are the same.
The first argument is a position object for the arbitrary point. The second argument is a position object for the center of the circle, and the third argument is a real number for the radius of the circle. Returns a position object or nil.
If pos-to-return is nil or unspecified, then a new position object is created and returned. Otherwise pos-to-return should be a position object, which will be modified and returned.
As usual, position objects should contain integers. See make-position. See also radial-line-circle-intersection-x-y.
function, cg package
Arguments: point-x point-y circle-center-x circle-center-y radius
Returns as multiple value the coordinates of the point on the edge of a circle where it is crossed by a line that passes through the center of the circle and through an arbitrary point. Returns nil if the circle center and the arbitrary point are the same.
The first two arguments are real numbers for the X and Y coordinates of the arbitrary point. The third and fourth arguments are real numbers for the coordinates of the center of the circle, and the last argument is a real number for the radius of the circle. Returns two real numbers for the X and Y coordinates of the intersection point, or nil.
See also radial-line-circle-intersection.
Generic Function, cg package
Arguments: tab-control
Returns the value of the ragged-right property of its argument, which must be an instance of the tab-control class.
This property determines whether multiple rows of tabs on a tab-control may have empty space to the right rather than filling the width of the tab-control. If nil (the default), multiple rows of tabs will be made as wide as necessary in order to fill the width of the tab-control; this choice has a neater appearance though it can result in some tabs being much wider than needed to contain their text. If true, multiple rows of tabs are each only as long as necessary to contain the tab text with standard margins; this choice may result in an odd appearance when one row hangs over a shorter row below it.
When all of the tabs fit within a single row, the tabs are never made wider, since there cannot be a shorter row for a longer one to hang over.
The ragged-right property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :ragged-right initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
ragged-right is a property of the tab-control class.
Generic Function, cg package
Arguments: standard-object
Returns the value of the range property of a dialog-item, which indicates the set of valid values from which the end user may interactively choose. The setf of this function may be used to replace the range of a dialog-item, at which time the dialog-item will be redrawn automatically if needed to display the new range.
A variety of dialog-items (widgets) have a range property, though the meaning varies depending on the type of widget. Among them are single-item-list, multi-item-list, and combo-box. More specific information may be found on the documentation pages for each widget class.
Most widgets that use a range use one of two basic types:
A list of discreet choices, where the value of the widget is one or more of these choices. multi-item-list, single-item-list, outline, and dropping-outline, for example, use this type of range.
A list of two numbers (a minimum value followed by a maximum value) indicating a continuous range of choices, where the value of the widget is a number within this range (including the boundary values). vertical-scroll-bar, horizontal-scroll-bar, and trackbar widgets are among those that use this type of range.
When the range is a list of discreet choices, some widget classes use a list of arbitrary objects that can serve directly as the value of the widget, while other widget classes use a list of more specialized objects that encapsulate the values. The classes single-item-list, multi-item-list, and combo-box are of the first type. On the other hand, an outline uses a range where each member is an outline-item object, a list-view's range contains list-view-items, a multi-picture-button's range contains button-infos, a tab-control's range contains tab-infos, and a header-control's range contains header-infos.
When a range contains specialized objects, then the values of these objects are used for the value of the widget itself, rather than using the range members directly for the widget value. For example, while a single-item-list range would simply be the list of symbols (:one :two :three) to allow the value of the widget to be one of those three symbols, an outline whose value may be one of those symbols would have a range whose members are outline-items, where the value of each outline-item is one of the symbols.
Sometimes the value of a widget that has a range is a single range value, and sometimes it is a list of zero or more range values. For most widget classes this depends on the class; for example, the value of a single-item-list or tab-control is always either a single value from the range or else nil if no choices are selected, while the value of a multi-item-list, list-view , or multi-picture-button is always a list of zero or more range values. For an outline, on the other hand, whether the value is a list depends on whether the multiple-selections property of the widget is turned on.
Generic Function, cg package
Arguments: value-axis
Returns the value of the range-bottom property of a value-axis. The value may be set at creation time by passing the range-bottom initarg, or any time later by calling (setf range-bottom).
A value to use for the low end of a value-axis in a chart-widget. The value should be a real number, or else nil to have the value computed automatically. The default value is nil.
When the value is a number, it should typically be less than or equal to the smallest data value that is being charted, or at least lower than the smallest value that you are interested in viewing at the moment.
When the value is computed automatically, a relatively "round" number is chosen that is equal to or somewhat less than the smallest data value. If set-chart-value is later called to add a value that is less than the current automatically computed range bottom, then a new range bottom will be computed to encompass the new value.
The value should be less than the range-top. To make the values increase in the atypical direction, use invert-axis rather than a range-bottom that is greater than the range-top.
To force a new range bottom to be computed (when the value of this property is nil), call update-chart-widget. This may be useful to recompute the range after set-chart-value has been used to modify values so that the data range is smaller, or if something has changed to cause the widget's chart-value-returner function to return a different range of values.
See also major-tic-increment and minor-tics-per-major-tic.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: dialog-item
This function has been deprecated, and will no longer ever be called beginning with the 8.0 release. It had been used only when an application replaces the range of a dialog-item, to determine whether the new range is equivalent to the old one, removing the need for side effects. This function had never been made into a property, and so was not saved with form windows. The dialog-item's on-change-test is now used instead on corresponding pairs of values in the range. If you set the value of this function to anything special, you should modify on-change-test instead.
See cg-events.html for information about event handling in Common Graphics.
Generic Function, cg package
Arguments: outline item-value range
Called when an outline-item is being closed to return the list of subitems to retain. The default method returns the list of subitems stored on the outline-item whose value is item-value.
Generic Function, cg package
Arguments: outline item-value range
Returns the list of child outline-items that an outline-item should display when its state is :open. This generic function is called internally whenever an outline-item is opened, either interactively by the end user or programmatically by calling (setf state) on the outline-item or open-outline-item-value on its value. The returned value is then stored as the new range of the outline-item.
The default method returns the current list of outline-items that is stored as the value of the range property of this outline-item. An application may supply a custom range-on-open method for an outline subclass in order to create most of the outline-items lazily if and when the end user opens each parent item. If all outline-items are instead created when creating the outline itself (or if they are added later with add-outline-item or add-outline-item-value), then there is no need to write a range-on-open method.
outline is the outline control that the outline-item being opened is on. item-value is the current value of this outline-item. range is the list of child items currently stored as the range of the outline-item.
When a custom range-on-open method creates new outline-items, these items typically do not in turn have child items yet, because such items would be created later if and when range-on-open is further called for the items being created now. The outline will not know at this time whether range-on-open would later return further child items, and so by default would draw the new items as leaf nodes. To prevent this from happening, the has-range-on-open property of each new item being created should be set to true if that item is expected to have child items if and when it is opened later.
The user is allowed to open all descendent items of an outline-item either by Control-clicking its icon or by selecting the item and pressing control-right-arrow. This could cause many items (or even an infinite number if items loop) to be opened if range-on-open methods are written in a way that allow that. If this recursive-opening operation is taking a long time, the user can press the Escape key to interrupt the operation and display whatever items have been opened so far.
Below is the range-on-open method from the Navigator dialog basic outline example.
;; The generic function range-on-open is called whenever an
;; outline-item is opened. We add this method to lazily open the
;; outline-items in the outline in the right half of the dialog.
(defmethod range-on-open ((outline my-class-outline) item-value range)
;; If this item has already been opened, then the range we gave
;; it last time is passed back in on this call. Assume that the
;; set of subclasses we found previously is still current, and
;; just return them again to show the same subclasses this time.
(or range
;; If no child items were passed in, then either this
;; class has no subclasses or this outline-item has not
;; yet been opened. So find the subclasses for the latter
;; case and create new outline-items for them the first
;; time the user opens this item.
(mapcar #'make-subclass-item-lazily
(mop:class-direct-subclasses item-value))))
;; This function is used by the outline in the right half of the dialog
;; to create outline-items "lazily" for the direct subclasses of a class
;; when that class' outline-item is opened by the user.
(defun make-subclass-item-lazily (class)
(make-instance 'outline-item
:value class
:state :closed
;; Since this outline is opening items lazily, Common Graphics doesn't yet
;; know if the outline-item is REALLY a "leaf" with no sub-items.
;; So check ahead for subclasses of this subclass, and if there
;; are any then tell the outline to draw this item as an
;; openable item rather than as a leaf.
:has-range-on-open (and (mop:class-direct-subclasses class) t)))Generic Function, cg package
Arguments: grid-column
Returns (or sets with setf) a function to return the list of values for a cell that is in a combo-box-column-mixinnil rather than a function, in which case no choices are displayed by the combo-box. The default value is nil.
For example, if the grid column that a range-reader is on is displaying the department of each employee that is displayed in a grid row, then the range-reader function might take an employee as its argument and return a list of the departments into which that employee could be moved. The employee grid example can be found on the Examples tab of the Navigator dialog.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: value-axis
Returns the value of the range-top property of a value-axis. The value may be set at creation time by passing the range-top initarg, or any time later by calling (setf range-top).
A value to use for the high end of a value-axis in a chart-widget. The value should be a real number, or else nil to have the value computed automatically. The default value is nil.
When the value is a number, it should typically be greater than or equal to the largest data value that is being charted, or at least greater than the largest value that you're interested in viewing at the moment.
When the value is computed automatically, a relatively "round" number is chosen that is equal to or somewhat greater than the largest data value. If set-chart-value is later called to add a value that is greater than the current automatically computed range top, then a new range top will be computed to encompass the new value.
The value should be greater than the range-bottom. To make the values increase in the atypical direction, use invert-axis rather than a range-top that is less than the range-bottom.
To force a new range top to be computed (when the value of this property is nil), call update-chart-widget. This may be useful to recompute the range after set-chart-value has been used to modify values so that the data range is smaller, or if something has changed to cause the widget's chart-value-returner function to return a different range of values.
See also major-tic-increment and minor-tics-per-major-tic.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
This operator is no longer defined and the symbol naming it has been removed. The operator existed but had no effect in earlier releases.
Generic Function, cg package
Arguments: row column row-number column-number
This generic function may be called to retrieve a value from an application's master data to display in the grid cell defined by the row and column arguments. The row and column arguments are objects such as are returned by calling subsections on a grid-row-section or grid-column-section. (An alternative function where you can instead pass row and column names or indexes is cell-value.)
The row-number and column-number arguments define which replication of replicated rows or columns is being addressed (see section-count).
Typically read-cell-value is called by a draw-cell method to find the value to draw in a particular cell. If the grid column uses one of the built-in grid-column classes such as editable-text-column-mixin, then the draw-cell method that is supplied with the built-in column class will call read-cell-value internally. Otherwise an application may supply custom draw-cell methods that call read-cell-value. The default read-cell-value method (shown below) first looks for the common grid paradigm where each grid row represents a data object (such as an employee) and each grid column represents an attribute of those objects (such as an employee's department). Next it will check if the (more obscure) data-slot approach is being used, or else if the cell is a special header-cell that provides a label. Last, it will look for a value that is automatically saved within the grid-widget itself when no means has been provided for writing cell values back into application objects; in this case the application would need to call cell-value or read-cell-value to find the current data.
(defmethod read-cell-value ((row grid-row)(column grid-column)
row-number column-number)
(declare (ignore row-number column-number))
;; This is default read-cell-value method, which is called to find
;; a value to display in a grid cell when no more specific read-call-value
;; method has supplied a value.
;; First, if the grid-row has a data-object that holds values to display
;; in that row, and the grid-column has a data-reader function to read that
;; column's values from objects, then find the value to display in that way.
(let ((data-object (data-object row))
(data-reader (data-reader column))
(slot-spec (data-slot column)))
(cond ((and data-object data-reader)
(funcall data-reader data-object))
;; If the column does not have a data-reader, but it does have
;; a data-slot specifier (for following a path through slots to
;; reach the value to display), then go with that.
((and data-object slot-spec)
(direct-or-indirect-slot-value data-object slot-spec))
;; Next, if this cell is in a grid-section named :header, and the
;; intersecting row or column's header-cell child has been given
;; a label, then use that label.
((property-value-for-header row column 'label))
;; In the end, if no special means has been set up for finding
;; a value in the application's own data or in a header cell, then
;; fetch a value that the grid-widget itself stored for this cell.
;; This is internal functionality where the default write-cell-value
;; behavior stores the value in a plist on the grid-row, where
;; the key is the grid-column.
(t (getf (cell-values row) column)))))The default method may be used for cells that fit this paradigm if the application has therefore supplied data-object values for the grid rows and data-reader functions for the grid columns. For grids that do not fit the object-rows-and-attribute-columns paradigm, the application could either supply a read-cell-value method that reads grid data from the application in a custom way, or else not use read-cell-value at all in its draw-cell methods.
For example, a draw-cell method to display a pixmap representing each employee's department could be written as follows (where the application has supplied a department-pixmap function):
(defmethod draw-cell ((row employee-row) (col department-column)
subrow-num subcolumn-num cell-box stream)
(let* ((department (read-cell-value row column subrow-num subcolumn-num)))
(copy-to-stream (department-pixmap department)
stream cell-box)))The above call to the default read-cell-value method depends on the grid row having a data-object (which would typically be an instance of the "employee" class), and on the grid column having a data-reader that is the name of a function, such as employee-department, that will return the department of that data-object. Alternately, since the above method already knows that the column is a department-column, instead of calling read-cell-value it could instead call (employee-department (data-object row)).
The row-number and column-number arguments are new to version 6.2. Applications that define methods on this generic function must add the new parameters to the method definitions. And any application calls to this generic function must pass the new arguments (just pass zeros to retain the old behavior). See the new example on the Examples tab of the Navigator dialog called Grid-widget: a basic replicated editable-text column to see how to write a read-cell-value method that uses these handy new arguments.
See also write-cell-value and the description of the grid-widget.
Function, cg package
Arguments: string &optional package eof-error-p eof-value &key start end preserve-whitespace
Like read-from-string and takes similar arguments and behaves the same when there is no error (except for the package argument, see below). But if an error is signaled during the read, this function catches the error and returns nil, the value of the :end argument, and the condition signaled.
read-from-string does not accept the optional package argument. If supplied, it must be a package object, or a string or symbol naming a package. The value of *package* is bound to that package while the string is read.
Generic Function, cg package
Arguments: pane &key path
Reads the links that were saved to path and establishes them as the current links of pane. path defaults to the file of pane except with the extension changed to .lin. This is done automatically when rich-edit-open is called, assuming that save-links has been turned on for pane and the links file exists. read-links-file may be useful for applications that do not use rich-edit-save and rich-edit-open to save and restore rich text.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: standard-object
Returns the value of the read-only property of its argument. This property determines whether the user may enter text into an editable-text, a multi-line-editable-text, a lisp-text, or a multi-line-lisp-text control; or into a text-edit-window, a text-edit-pane.
static-text controls are always read-only. This property allows editability to be toggled programatically in non-static text controls.
read-only is a property of the editable-text, lisp-text, multi-line-editable-text, multi-line-lisp-text, and text-edit-pane classes.
Function, cg package
Arguments: stream &optional package eof-error-p eof-value
Like read and takes similar arguments and behaves the same when there is no error. But if an error is signaled during the read, this function catches the error and returns nil and the condition signaled.
Function, cg package
Arguments: pathname-or-namestring
Returns a Lisp string containing the contents of the file at pathname-or-namestring. This may be used for either a plain-text or rich-text file.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: stream &optional invalidate-p update-colors-p
The function maps the current palette of stream into the hardware palette, so that the window's colors are in active use. This may be useful after another window (or another application) has mapped its colormap, possibly displacing from the single hardware palette the palette that was established for stream via (setf palette). stream should be a cg-stream.
When a top-level Allegro CL window is brought in front of other top-level windows (as when Alt-Tab is used), then the palette of that top-level window is realized automatically. Thus, calling realize-palette is not necessary unless you use multiple palettes under a single top-level window or some palette assigned to a lower-level window is not also assigned to its top-level parent. Recall that a top-level window is one whose parent is (screen *system*) (see screen and *system*).
Generic Function, cg package
Arguments: multi-picture-button
Returns the value of the recessed property of its argument. This property determines whether buttons appear recessed or appear to protrude.
recessed is a property of the multi-picture-button class.
Generic Function, cg package
Arguments: object
Returns a Lisp form which, when evaluated, will create an object as similar as possible to the one passed in. This is chiefly used internally to generate the code to recreate the interactively laid out dialogs of an IDE project, though it may prove generally useful for saving objects as Lisp code that can recreate the objects in later Lisp sessions or at runtime. Built-in methods are provided for basic Lisp objects and windowing objects, though an application could supply further methods for its own objects.
Returns nil if such code cannot be determined.
Generic Function, cg package
Arguments: drawable stream
Called whenever a drawable control needs to be redrawn, such as when it is uncovered. drawable is the drawable control itself. stream is the stream on which to draw.
If the use-bitmap-stream property of the control is true, then stream will be the bitmap-stream of the control; otherwise stream will be the visible window of the control.
If use-bitmap-stream is true, then redisplay-event will be called only when the application explicitly calls update-drawable on the drawable; otherwise whatever is currently drawn on the bitmap-stream is used to refresh the visible window as needed.
The default redisplay-event method essentially just calls the on-redisplay handler of the drawable if it has one. The on-redisplay handler is the more typical place to place custom drawing code.
Generic Function, cg package
Arguments: outline outline-pane item x y key line-height half-line-height erase-p focus-index-p icons-p unavailable widget-font widget-backcolor widget-forecolor printer
This function is called by the system when an outline-item is drawn. Programmers could provide a method for drawing an outline item to draw a custom picture in an outline-item in place of the usual string.
outline is the outline control, and outline-pane is its window.
item is the outline item whose value needs to be drawn (the icon and line are drawn automatically elsewhere)
x and y are the coordinates of the top-left of this item, to the right of where the icons and lines are drawn.
key is the function for converting the outline-item value to the actual string to display.
line-height is the vertical size of the space allotted for this item. half-line-height is half that value.
erase-p is true if and only if the background of the item should be cleared.
focus-index-p is true if and only if this item has the keyboard focus.
icons-p is true if and only if this outline should draw icons.
unavailable-p is true if and only if this item should be grayed out and not respond to the mouse.
Generic Function, cg package
Arguments: window &optional box
This generic function is called by Common Graphics as needed in order to redisplay all or part of a window. Redisplay may happen either when part of the window becomes uncovered, or when the application has called invalidate to explicitly cause the window to be redrawn. An application draws the content of its windows by writing redisplay-window methods for the application's various window subclasses that it has defined.
Note that the application itself should never call redisplay-window. If the content of the window needs to change, the proper technique is to call invalidate to tell the operating system that the window needs to be redrawn, and then to redraw the content inside the redisplay-window method as usual. The operating system will then send the paint message (which causes Common Graphics to call redisplay-window) only when all other event-handling activity in the thread has exited. This design is a feature of the operating system to avoid redundant redisplays, which not only slow down the interface but also may cause annoying screen flashing. If the window needs to be redrawn immediately, the application should call update-window just after calling invalidate. That causes redisplay-window to be called at that time and informs the operating system that the window is now up-to-date so a later paint message is not necessary. To reduce flashing effects when a window is scrolled, resized, or animated, enable the double-buffered property of the window.
The box argument indicates the portion of the window that needs to be redrawn. In the simplest case, a redisplay-window method can just ignore this box and redraw everything on each call; in this case the OS will clip at the box boundaries so that nothing is actually drawn outside the box. But the method will likely be more efficient if it takes note of the box and does not even attempt to draw any objects that are known not to intersect with the box. The box argument is optional for backward compatibility reasons only; in fact, a box is always passed, and so methods do not need to check that a box has been passed.
Certain classes of windows do not need to be given redisplay-window methods. In particular, a bitmap-pane (auto-instantiated with a bitmap-window) already has a redisplay-window method, which simply copies the window's backing store to the visible window. (But remember that the backing store memory bitmap can consume a lot of virtual memory, so it's usually best to use a "plain" window with a custom redisplay-window method unless the extra redisplay speed of a bitmap-pane is really needed.) And a text-edit-pane is redrawn by the operating system, since it is actually a control supplied by the OS.
An application may override the default method of this and several other generic functions in order to implement a custom scrolling scheme that scrolls by logical picture objects rather than by pixels. See the source code of the example entitled Scrolling by arbitrary objects rather than pixels on the Examples tab of the Navigator dialog for a complete example. More on this point and a list of the relevant generic functions can be found on the horizontal-scroll-bar and vertical-scroll-bar pages.
See cg-drawing.html for a discussion of the uses of redisplay-window, invalidate, and update-window.
Generic Function, cg package
Arguments: text-edit-pane
This function has an effect only in Windows desktop mode. In CG/JS mode, undo and redo in a text-editing widget can be done only by typing Control+Z and Control+Y (or Command+Z and Command+Y on a Mac). That lets the web browser perform its built-in behavior, which cannot be invoked programmatically. See also send-undo-keystrokes-to-server.
Modifies window so that it is in the state that it was in just before the most recent call to undo-command on the window. This is done only if there have been no user text edits since undo-command was called, other than other calls to redo-command. If redo-command is called multiple times in succession, any further text edits that were undone by successive calls to undo-command are redone until there are no more to redo.
The window should be an instance of the text-edit-pane class or one of its subclasses. This includes rich-edit-panes.
Generic Function, cg package
Arguments: object &key check-ancestors
Returns true if there is a delayed redraw on object. Object's ancestors are checked if the check-ancestors keyword argument is specified true.
Generic Function, cg package
Arguments: pixmap
Creates and returns a pixmap that is the same as the pixmap argument, except with the pixel values swapped across a vertical axis to produce a mirror image of the original. The argument should be a pixmap object. See cg-pixmaps.html for information on creating pixmaps.
This function replaces reflect-texture-in-x, which was available in releases prior to 7.0 but is no longer supported.
Generic Function, cg package
Arguments: pixmap
Creates and returns a pixmap that is the same as the pixmap argument, except with the pixel values swapped across a horizontal axis to produce a mirror image of the original. The argument should be a pixmap object. See cg-pixmaps.html for information on creating pixmaps.
This function replaces reflect-texture-in-y, which was available in releases prior to 7.0 but is no longer supported.
Generic Function, cg package
Arguments: region
Returns a box that indicates the smallest orthogonal rectangle that completely contains a hotspot region. region should be a value that is valid for hotspot-region.
This function could be useful for finding a box to invalidate to ensure that a hotspot is entirely redrawn (or undrawn). A shortcut for that is to simply call invalidate on the hotspot itself rather than on its parent window, but perhaps there are similar uses for region-box.
Generic Function, cg package
Arguments: window &key fine-touch want-palm
Causes the specified window to receive touch messages thereafter, rather than gesture messages. (Gesture messages are otherwise received by default.) After calling this function, a series of calls to touch-event will be made for any touchscreen gesture, rather than calls to gesture-event.
If fine-touch is true, Microsoft says that the window then "prefers noncoalesced touch input". If nil or unspecified, then it does not. See Microsoft documentation for the meaning of coalesced.
If want-palm is nil or unspecified, then some events are delayed a bit in order to determine that some touches are inadvertent palm touches, which are then ignored and no call to touch-event occurs. When want-palm is true, this is not done and touch-event will be called even for palm touches. If you want the fastest possible response, then pass this as true.
This function can be called again on a window when touch gestures are already in effect, to simply change the values of the keyword arguments.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: plot-view
Returns the regression-line-colors property of a plot-view object, which is associated with a plot-widget control. The value may be set at creation time by passing the :regression-line-colors initarg to make-instance, or any time later by calling (setf regression-line-colors).
This is a list of colors for regression lines for the multiple chart-objects of the plot-widget. The first element of the list is the color to use for the first chart object, and so on, cycling back through the list as needed.
Each value in the list should be either an RGB color object (see make-rgb) or a constant symbol or global variable whose value is an RGB. The default value is a list of the color variables blue, dark-green, red, dark-magenta, dark-cyan, gray, black, and dark-yellow.
The regression lines are drawn only if the draw-regression-lines property of the plot-view is true.
Generic Function, cg package
Arguments: plot-view
Returns the regression-line-dashings property of a plot-view object, which is associated with a plot-widget control. The value may be set at creation time by passing the :regression-line-dashings initarg to make-instance, or any time later by calling (setf regression-line-dashings).
This is a list of line dashing styles for regression lines for the multiple chart-objects of the plot-widget. The first element of the list is the dashing style to use for the first chart object, and so on, cycling back through the list as needed.
Each value in the list should be one of the keyword symbols that is a valid value for the line-dashing property of a stream, such as :solid or :dash. The default value is a list of the keyword :solid, to draw all regression lines as non-dashed lines.
The regression lines are drawn only if the draw-regression-lines property of the plot-view is true.
Generic Function, cg package
Arguments: plot-view
Returns the regression-line-widths property of a plot-view object, which is associated with a plot-widget control. The value may be set at creation time by passing the :regression-line-widths initarg to make-instance, or any time later by calling (setf regression-line-widths).
This is a list of line widths for regression lines for the multiple chart-objects of the plot-widget. The first element of the list is the line width to use for the first chart object, and so on, cycling back through the list as needed.
Each value in the list should be a positive integer. The default value is a list of the number 2, to draw all regression lines two pixels thick.
The regression lines are drawn only if the draw-regression-lines property of the plot-view is true.
Generic Function, cg package
Arguments: lisp-edit-pane &key pretty-print
Reindents the selected Lisp code or top-level Lisp form in the specified lisp-edit-pane. If any text is currently selected, then that is the text that will be reindented; otherwise the top-level form that the text cursor is inside (or after) will be reindented.
If pretty-print is nil (the default), then spaces are simply added to or removed from the beginning of each line as needed for conventional Lisp source code indentation. If pretty-print is true, then the top-level form is pretty-printed as a whole into the lisp-edit-pane (fitting the text to the current window width), replacing the previous version of the form. Pretty-printing will likely wrap the form differently (changing how much code appears on each line), and will always remove any comments that were in the top-level form.
The text cursor should end up in the same logical position as before the operation if pretty-print is nil; this is not feasible if pretty-print is true. In either case, parenthesis-matching will be updated after the operation (see parentheses-matched).
Reindenting may not work correctly if the text is auto-wrapped. Auto-wrapping will happen if the lisp-edit-pane has no horizontal scrollbar and one or more of its text lines is longer than the interior width of the window. Therefore, a lisp-edit-pane in which reindenting will be done should have a horiztonal scrollbar by setting its scrollbars property either to :horizontal or (more typically) to t (which is the default).
See also reindent-single-line.
Generic Function, cg package
Arguments: lisp-edit-pane
Reindents the line of text of a lisp-edit-pane that the text cursor is currently in. This is done by adding or removing spaces at the beginning of the line as needed to indent the line within its surrounding Lisp form, according to Lisp source code indenting conventions.
An application could make the TAB key call this function, for example, as the IDE editor does. (See virtual-key-down and set-event-function.)
See also reindent-region.
Generic Function, cg package
Arguments: window
Releases the mouse from window. See capture-mouse.
Generic Function, cg package
Arguments: property
Returns true if when the value of property is changed, the component will have to be recreated to reflect the new value. For components that are controls on forms, the recreation is done automatically and no additional programming is necessary. If the component is a form, the change is made when the form is run.
However, if the component is a running dialog or a control on a running dialog, then changing the property value will have no visual effect (unless the programmer adds code to replace the control) and so changing the property value is probably not worth doing.
Generic Function, cg package
Arguments: key &optional (subkey (default-application-window-subkey))
Uncaches a window (added by add-application-window or find-or-make-application-window) so that it can no longer be retrieved later by calling find-application-window on its key or subkey. The key and subkey arguments should be eq to the ones that were passed to add-application-window for the desired window.
Generic Function, cg package
Arguments: list-view column-name
Removes the list-view-column whose programmatic name is column-name from list-view. Does nothing if there is no such item. An error will be signaled if an attempt is made to remove the first (leftmost) column, since this column is special and cannot be removed. (The first column can be modified, however.)
Generic Function, cg package
Arguments: component dialog
Removes the component specified by the first argument (actually the component object or its window can be the value of the first argument) from dialog.
Generic Function, cg package
Arguments: tab-control tab-id widget
Removes the control identified by the widget argument from tab-control if it is on the tab whose programmatic name is tab-id.
Generic Function, cg package
Arguments: menu items
Removes items from menu. Items must be a list of menu-items or a single menu-item. Returns items.
Function, cg package
Arguments: event-synonym
This function removes the keyboard accelerator associated with event-synonym. event-synonym should be a character or a list of modifier keys and a character denoting the keyboard event that should no longer have a global effect. Global keyboard accelerators are established with add-global-keyboard-accelerator.
Generic Function, cg package
Arguments: header-control header-id
Removes the header whose programmatic name is header-id from header-control.
Generic Function, cg package
Arguments: window hotspot
Removes hotspot from window.
Generic Function, cg package
Arguments: list-view item-name
Removes the item identified by item-name from list-view.
Generic Function, cg package
Arguments: outline outline-item &key no-redisplay
This function works like remove-outline-item-value except that the second argument is an outline-item rather than its value. Passing the item ensures that the correct one is removed when other items may have the same value as it.
Generic Function, cg package
Arguments: outline item-value &key * no-redisplay*
Deletes the outline-item whose value is item-value from outline. (If multiple items have the indicated value, then only the first is deleted. Use remove-outline-item instead to avoid this ambiguity.) If the deleted item has any descendent items, they are deleted as well.
If no-redisplay is true, then the changed part of the outline is not redrawn automatically as usual. This may be useful for efficiency if multiple items are being deleted, where remove-outline-item-value can be called several times with no-redisplay specified as true, and then invalidate called a single time on the outline widget to redraw it once only.
See also add-outline-item-value and outline-item-removed.
Generic Function, cg package
Arguments: window &optional (status-bar (status-bar window))
Removes the status-bar dialog pane specified by the optional argument from window. Any child windows that were adjacent to the status-bar will be resized to fill the emptied space.
Generic Function, cg package
Arguments: tab-control tab-info-or-name &key remove-components
Removes tab-info-or-name, which may be a tab-info object or its name (returned by (name tab-info) -- see name) from tab-control, which must be a tab-control. The tab can be restored with restore-tab. If remove-components is specified true, the components on the removed tab are deleted (so they will not be there when the tab is restored). If that argument is nil (the default), the components remain (they are still siblings of the tab-control) but not visible until the removed tab is restored.
Generic Function, cg package
Arguments: window toolbar &optional no-resize-child-windows
Removes toolbar from window. Any remaining toolbars are moved to fill in the gap between them. Any child panes that were adjacent to the toolbars are stretched to fill in the emptied space, unless no-resize-child-windows is true.
Generic Function, cg package
Argumentstray-item:
Removes the specified tray-item from the system tray unless it is not currently there, in which case nothing is done.
tray-item must be an instance of the tray-item class, as created with make-instance.
See the description of the tray-item class for an example.
Function, cg package
Arguments:
Returns a list of all the status-bars that have been removed from windows using remove-status-bar, and which have not been either added back to a window or closed.
Function, cg package
Arguments:
Returns a list of all the toolbars that have been removed from windows using remove-toolbar, and which have not been either added back to a window or closed.
Generic Function, cg package
Arguments: outline outline-item new-item-value &key no-redisplay
Changes the value of outline-item in outline to new-item-value. If no-redisplay is true, the outline will not be redrawn because of this action. The changes will be reflected when the outline is redrawn for some other reason.
Generic Function, cg package
Arguments: stream pixmap to-box &key (mode po-replace) (offset-x 0) (offset-y 0)
Fills a rectangular area with a pixmap by tiling the pixmap as needed when the area to be filled is wider or taller than the pixmap itself.
stream is a graphical-stream on which the pixmap will be drawn.
pixmap is a pixmap object. See cg-pixmaps.html for an overview of pixmaps.
to-box is a box, as created with make-box, that specifies the area of the stream to be filled.
mode may be any value that is valid as the paint-operation of a stream. The default is the value of po-replace.
offset-x and offset-y are integers that specify how to align the pixmap with the left and top sides of the filled area. By default they are zero, which will align the left and top of the pixmap image with the left and top edges of the filled area. Otherwise the tiled pixmap images will be shifted leftward by offset-x and upward by offset-y, clipping off part of the pixmap at the left and top sides of the filled area.
To fill an area by stretching a pixmap rather than by tiling it, call copy-to-stream instead, passing a box as the to-box-or-position argument.
function, cg package
Arguments: condition
This is the default value of the default-error-handler-for-delivery option of a project in the IDE. It simply displays a dialog telling the user that an unexpected error has occurred, and then exits Lisp.
See default-error-handler-for-delivery for more information.
Function, cg package
Arguments: minimum-milliseconds
This function may be useful in certain cases where the web browser is delaying the refreshing of the screen while it is busy handling many requests from Lisp. This function simply sends a message to the browser that requests a dummy reply. For reasons that are not clear, sending the reply will trigger the browser to refresh the screen at that time. The Lisp IDE uses this during a Find In Files search.
Calling this function frequently can slow down the operation that's being done. To alleviate that, minimum-milliseconds can be passed as a positive integer. In that case, the request to the browser will be sent only if it has been at least that many milliseconds since the previous time that this request was sent. Passing 500, for example, would ensure that the display is refreshed at least every half second, without slowing things down much.
Function, cg package
Arguments:
Loads the cg-acache module if it has not already been loaded. Loading that module will also cause the newest version of AllegroCache that exists in the code subdirectory of your Allegro installation to be loaded.
Those modules are needed when using an object-editor dialog or class-grid widget whose edited-class is a persistent (AllegroCache) class.
Common Graphics and the IDE attempt to load these modules automatically when needed, but this function is provided in case an application needs to load them at other times. Neither AllegroCache nor the cg-acache module are initially present in the IDE.
Generic Function, cg package
Arguments: cg-configuration
This option has an effect only on the Windows platform.
This Common Graphics configuration option specifies how the right-hand Alt key is handled. This key is sometimes known as the AltGr key, especially on European keyboards.
If the value is nil, then Common Graphics handles the righthand Alt key as a regular Alt key, just as it does for the lefthand Alt key. Keystrokes with this key held down will call virtual-key-down methods as usual, or invoke menu commands whose event-synonym shortcuts use alt-key.
If the value is true, then Common Graphics will not handle keystrokes at all when the righthand Alt key is held down, and will instead pass the keystrokes directly back to the Windows operating system. This is needed with some keyboards for entering characters for which the keyboard does not have dedicated keys.
The default value is true, to allow the AltGr key to be used for alternate character input by default. The following form sets the option to nil:
(setf (reserve-righthand-alt-key (configuration *system*)) nil)Generic Function, cg package
Arguments: standard-object
Returns the value of the resizable property of the argument. This property determines whether something (typically a window) can be resized by a user with the mouse: it can be if the value of the property is true and it cannot be if the value is nil. The property does not affect programmatic resizing, with, e.g., (setf height) or (setf width).
The resizable property may not be changed on an existing window, and must instead be specified with the inspector when designing a window (using a form) or with the :resizable initarg of make-window. (It can be changed using the inspector when designing a form but not for a running window or control, either in the IDE or in an application.)
For a grid-row or grid-column, this property determines whether the user may interactively resize the row or column. A resizable grid-row may be resized interactively only by clicking it in its cells that also lie in columns that are instances of row-sizing-column-mixin. Likewise, a resizable grid-column may be resized interactively only by clicking it in its cells that also lie in rows that are instances of column-sizing-row-mixin. The setf of this function may be called at runtime to change the resizable status of a row or column.
Generic Function, cg package
Arguments: window position
Sets the interior width and height of window to the x and y components of position respectively. Returns the actual size set if successful, or nil if unsuccessful. (See track-limits)
Function, cg package
Arguments: &rest pixmaps
Calls cache-pixmap on each of the argument pixmaps.
Generic Function, cg package
Arguments: text-edit-pane
Sets the right-margin of a text-edit-pane to reflect the number of characters that will fit within the interior width of the window. Specifically, this is the interior-width of the window minus its text-edit-margins. This will be a useful value only if the window's font is a fixed-width font.
restore-right-margin is called automatically whenever a text-edit-pane is created or resized, and so an application probably has no need to call this function. An application should be able to evaluate the expression (right-margin text-edit-pane nil) at any time to find the number of characters that will fit onto one line of text. (If the window's horizontal scrollbar is enabled, then this is the amount of one line of text that can be scrolled into view at one time. See scrollbars.) The pretty-printer also uses the right-margin to format text within the visible interior width of a text edit pane.
Generic Function, cg package
Arguments: tab-control tab-info &key (index (index tab-info))
Puts tab-info, which should have been earlier removed from tab-control by remove-tab, back on tab-control, retaining the widgets that were on tab-info when it was removed from tab-control. (The argument must be a tab-info object, not its name.) Positions the tab so that it is the index'th tab from the left, where zero indicates the leftmost tab.
Macro, cg package
Arguments: (stream) &body body
Calls copy-graphics-context to save the current drawing style options of stream, then executes the body, and then calls set-graphics-context to restore the saved drawing style options. stream should be a cg-stream.
This allows the body code to arbitrarily set temporary drawing style options without explicitly setting each one back afterward. An unwind-protect is used to ensure that the final call to set-graphics-context is always performed (as long as the call to copy-graphics-context was completed successfully). Returns the values returned by the body.
See copy-graphics-context (where all the information in a graphics-context object is described), make-graphics-context, set-graphics-context, and graphics-context-p.
Generic Function, cg package
Arguments: object
Re-enables all drawing on object if it has been disabled at some point by a call to delay-redraw. object may be a window or a dialog-item (control). Refer to with-delayed-redraw for more information.
Generic Function, cg package
Arguments: multi-picture-button
Returns the value of the retain-scroll-arrows-always property of the argument. This property determines whether a multi-picture-button control will have scroll arrows drawn even when all of the buttons fit into the control's region.
retain-scroll-arrows-always is a property of the multi-picture-button class.
Generic Function, cg package
Arguments: window
This window property has an effect only when running in Windows desktop mode.
Returns whether window will continue displaying each of its scrollbars when there is nothing for it to scroll. The value may be set either by calling (setf retain-scrollbars) or by passing the :retain-scrollbars initarg to make-window when creating the window.
The default value is nil, meaning that scrollbars will go away when they can. You might want to set the value to true, for example, if you would like the interior size of the window to always remain the same, since removing a scrollbar increases the interior size.
A window's horizontal scrollbar is not needed whenever the window's page-width is no larger than its interior-width, and its vertical scrollbar is not needed when its page-height is no larger than its interior-height. This typically changes when a user resizes a window, though an application may also change the page-width or page-height at any time.
A window scrollbar will still not be displayed if it was not requested. So if the scrollbars property of a window is :vertical and its retain-scrollbars property is true, then it will always display a vertical scrollbar and never a horizontal scrollbar.
Function, cg package
Arguments: widget new-value old-value
The default on-click function for a cancel-button.
This function simply calls flag-modal-completion with a value argument of nil, if the widget's parent dialog is currently being invoked in the current process by a call to pop-up-modal-dialog. Otherwise it does nothing.
Function, cg package
Arguments: widget new-value old-value
The default on-click function for a default-button.
This function simply calls flag-modal-completion with a value argument of t, if the widget's parent dialog is currently being invoked in the current process by a call to pop-up-modal-dialog. Otherwise it does nothing.
Function, cg package
Arguments: struct
Returns the value of the blue component of its argument, which must be a rgb color object. See make-rgb.
Function, cg package
Arguments: rgb1 rgb2
Returns true if the two arguments, which must be rgb color objects, define the same color and returns nil otherwise. See make-rgb.
Function, cg package
Arguments: struct
Returns the value of the green component of its argument, which must be a rgb color object. See make-rgb.
Function, cg package
Arguments: object
Returns true if its argument is an rgb color object and returns nil otherwise. See make-rgb.
Function, cg package
Arguments: struct
Returns the value of the red component of its argument, which must be a rgb color object. See make-rgb.
Function, cg package
Arguments: rgb-triple
Returns the hls color object corresponding to the argument rgb color object. See make-rgb, make-hls and hls-to-rgb.
Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.
Generic Function, cg package
Arguments: rich-edit-ruler
Returns the name of the rich-edit control to which rich-edit-ruler (an instance of the rich-edit-ruler control class) is attached, if any, and nil otherwise. This property should be set only when creating the rich-edit-ruler by passing the name of the rich-edit control as the value of the :rich-edit initarg to make-instance.
When attaching a ruler interactively by dragging it onto a rich-edit control on a form, this property is set automatically.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: text-edit-pane
Calls ask-user-for-color to request a color from the user, and then (unless the user cancels the color dialog) calls (setf color) on text-edit-pane (a text-edit-pane) to set the current text color.
This function is called by the menu-bar and rich-edit-multipic widget that are built into a rich-edit-dialog, but could be called from an application in some other way as well.
Function, cg package
Arguments: text-edit-pane
Calls ask-user-for-font to request a font from the user, and then (unless the user cancels the font dialog) calls set-character-format on text-edit-pane (a text-edit-pane) to set the current font.
This function is called by the menu-bar and rich-edit-multipic widget that are built into a rich-edit-dialog, but could be called from an application in some other way as well.
Function, cg package
Arguments:
Returns a menubar suitable for use on a dialog that has one or more rich-edit controls. (A rich-edit-dialog is typically created with such a menubar already in place.) After putting this menubar onto a form in the IDE, the menubar may be further edited as desired for that particular form.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: pane
Clears the rich-edit-pane pane for editing a new file.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: pane &key path allowed-types
Reads a new file (specified by path) into the rich-edit-pane pane for editing.
path may be a pathname, a path namestring, or nil. When nil, ask-user-for-existing-pathname is called to ask for the file to edit.
allowed-types may be a value to pass as the allowed-types argument to ask-user-for-existing-pathname (if it is called), or nil to default to (("Rich text" . "*.rtf")).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: pane
Prints the contents of rich-edit-pane to a printer. The print job dialog will appear to prompt the user for the printer to print to. Returns nil if the user cancels from this dialog, and t otherwise.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: text-edit-pane &key (format :rich-text) (start 0) (end most-positive-fixnum) (return-crlf t)
This function returns a string for window (identified by text-edit-pane) from character position start to end. If start and end are not supplied, the entire contents are returned. If format is :rich-text (the default), then a rich-text string is returned. If it is :text, then a plain-text string is returned.
If end is not greater than start, then an empty string is returned. If format is :rich-text, this empty string is a special two-character string consisting of an open curly brace followed by a close curly brace. Otherwise it is the usual zero-length null string. The special empty string for rich text is the value of *empty-rtf-string*, and is used because it works as a valid rich text string with the rich-edit-control, while the standard Lisp null string does not.
The return-crlf argument no longer has any effect, and is kept for backward compatibility only. It was used on the Windows platform by an earlier version of the RichEdit control.
The setf function sets the text in window from start to end to be string. If start and end are not specified, the entire contents of window are replaced. If format is :rich-text (the default), then string should be a rich-text string, which will be inserted using its own formatting. If it is :text, then string should be a plain-text string, which will be inserted using the formatting at the current position of the text-edit-pane.
When format is :rich-text, string may be the value of *empty-rtf-string* to indicate a rich text string with no contents.
See also rich-edit-selected-range and its setf.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: pane &key (format :rich-text)
Saves the contents of the rich-edit-pane pane to its file.
This function simply calls rich-edit-save-as, passing the file property of pane as the path argument, and passing format as the format argument. The file property will contain the path that was specified in a prior call to rich-edit-open, rich-edit-save, or rich-edit-save-as, or else nil.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: pane &key path allowed-types format
Saves the contents of the rich-edit-pane pane to a new file named by path.
path may be a pathname, a path namestring, or nil. When nil, ask-user-for-new-pathname is called to ask for the path to which to save the contents.
format may be :rich-text (the default) to save rich text, or :text to save plain text. This argument is passed to rich-edit-range to retrieve the text to save.
allowed-types may be a value to pass as the allowed-types argument to ask-user-for-new-pathname (if it is called), or nil. When nil, the value will default to (("Rich text" . "*.rtf")) when format is :rich-text or to (("Text" . "*.txt")) when format is :text.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: text-edit-pane &key (format :rich-text)
The function returns a string for the currently selected text of window. Calling this function is the same as calling rich-edit-range and passing in the start and end of the current selection. If format is :rich-text (the default), then a rich-text string is returned. If it is :text, then a plain-text string is returned.
The setf function writes a string over the current selection of window. Calling it is the same as calling setf on rich-edit-range and passing in the start and end of the current selection. If format is :rich-text (the default), then string should be a rich-text string, which will be inserted using its own formatting. If it is :text, then string should be a plain-text string, which will be inserted using the formatting at the current position of the text-edit-pane.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: widget
Returns (or sets with setf) the rich-text string displayed in rich-edit, which must be an instance of the rich-edit control class. Using this widget property is similar to calling the function rich-edit-range on the window of the rich-edit control (the result of applying window to the control) and using the default values of the keyword arguments.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: rich-text-string
Creates and returns a plain-text string that is equivalent to rich-text-string except without any formatting. If the value of *empty-rtf-string* or any other rich text string with no content is passed, then the null string (a string of length zero) is returned.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: box
Returns the value of the right property of the argument. The right property is the location (when displayed) of the right side of an object in the coordinate system of its parent.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the right-attachment property of standard-object. This property determines how the distance between the object's right edge and the edge(s) of its parent window change when the parent gets resized.
The possible values and their effects are:
:right: object maintains a constant distance between its right edge and the right edge of its parent window whenever the parent is resized.
:left: object maintains a constant distance between its right edge and the left edge of its parent window whenever the parent is resized.
:scale: object maintains the same ratio of the distances from the left and right sides of its parent window whenever the parent is resized. I.e., if the right side was one-half of the way between the left and right edges of the parent before, then it is one-half of the way between the edges after resizing.
See also left-attachment, top-attachment, bottom-attachment, track-limits and resize-window.
Generic Function, cg package
Arguments: text-edit-pane
Returns the current indentation of the righthand side of a paragraph of text in a text-edit-pane, or the indentation indicated by the corresponding righthand slider of a rich-edit-ruler. In either case, the value is measured in points leftward from the rightmost position. When the text-edit-pane or rich-edit-ruler is resized, the right-indentation value will remain the same and the text (and/or slider) will remain indented by the same relative amount from the righthand side. (In releases prior to 6.1, this value was measured from the lefthand side, and so did not follow window resizing.)
The method for text-edit-pane returns the righthand indentation for the paragraph that contains the text cursor, or the first paragraph that is partly or wholly contained in the selected text, if any.
The setf method for text-edit-pane sets the righthand indentation of the body of the paragraph that contains the text cursor (or all paragraphs that are partly or wholly selected, if any). If there is a rich-edit-ruler associated with the text-edit-pane (see the function ruler), then the rich-edit-ruler's indentation will be automatically modified to match.
The method for rich-edit-ruler returns the position of the righthand slider.
The setf method for rich-edit-ruler moves the righthand slider of the ruler to the specified position. The slider will be constrained at position 0 (the rightmost position) if an attempt is made to move it to a negative position. If there is a text-edit-pane associated with the ruler (see the function rich-edit), then the paragraph in the text-edit-pane that contains the text cursor (or all paragraphs that are partly or wholly contained in the selected text, if any) will be automatically modified to match.
To read or modify multiple paragraph attributes of a text-edit-pane at once, see get-paragraph-format or set-paragraph-format. See also body-left-indentation and top-left-indentation.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: outline
Returns the value of the right-justification-width of outline. If true, then any text after a tab character in each outline-item's displayed string will be right-justified in a field that extends from the outline's tab position for that tab to a point that is right-justification-width beyond that point.
For example, if right-justification-width is 60, and a tab character in an outline-item's displayed string causes part of the string to tab over to a point 100 pixels from the left edge of the outline (because 100 is in the list of tabs for the outline), then that part of the string will be displayed with its right edge reaching to a point 160 pixels from the left edge of the outline. (Without a right-justification-width, that part of the string would have its left edge at 100 instead.)
Function, cg package
Arguments: text-edit-pane
Calls (setf justification) on text-edit-pane (a text-edit-pane) with the value :right. This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.
Generic Function, cg package
Arguments: graphical-stream &optional (stream-units-p t)
Returns the current right margin of a graphical-stream, measured from the left edge of the stream. The right-margin is initially the page-width of the stream, except as noted below. (setf right-margin) may be called to set the margin at any time.
If stream-units-p is true, as it is by default, then the margin is measured in pixels. If nil, it is measured in space character widths (see space-width).
Margin attributes are provided primarily to allow an application to keep a drawing within arbitrary margins by drawing everything within the coordinates returned by left-margin, top-margin, right-margin, and bottom-margin. Common Graphics also uses them in a few special ways, though, as described below.
When printing text to a graphical-stream while *print-pretty* is true, the pretty printer will add newlines to the text so that it fits within the line-length of the stream. The line-length is equal to the left-margin of the stream subtracted from the right-margin. An application that is drawing text to a graphical stream in some other way generally should ensure that the text does not extend past the right-margin of the stream.
For a text-edit-pane, the function restore-right-margin will set the right-margin to the interior width of the window minus its special text-edit-margins. This function is called automatically when a text-edit-pane is created or resized, which causes the pretty-printer to format text within the visible width of the window. Printing may be done beyond the right margin of a text-edit-pane, though, which will either extend its horizontal scroll range as needed if its horizontal scrollbar is enabled (see scrollbars), or otherwise wrap the text to multiple lines.
A printer stream's coordinate system has position (0, 0) at the printer-physical-offset of the printer. To allow an application to avoid dealing with this arbitrary offset, Common Graphics sets the margins of a printer stream to the distance from the physical offset to the margins selected by the user in the print job dialog or page setup dialog. This allows the application to maintain the requested paper margins by simply drawing everything within the four margins that were set up automatically. See *default-printer-left-margin* for more information.
Generic Function, cg package
Arguments: pixmap quarter-lefts &key name
Creates a copy of the specified pixmap object whose image is rotated by the specified number of quarter-left (counterclockwise) turns. The new pixmap will have the specified name if supplied, or else a unique gensymed name.
Generic Function, cg package
Arguments: texture quarter-lefts &optional texture-info
Modifies the pixels of texture so that it appears rotated by quarter-lefts quarter-left turns. If quarter-lefts is divisible by 4, then no rotation is needed, and the original texture is simply returned; otherwise a new texture is created and returned.
texture-info can be passed if the logical width or height of the texture is different than the actual width or height of the internal array; in this case the new internal array will be made as small as it can be to still hold all of the pixels for the logical width and height as specified in the texture-info.
Generic Function, cg package
Arguments: tab-control
Returns the number of rows needed to display the tabs of the argument tab-control. See the description of the tab-control class.
Generic Function, cg package
Arguments: grid-widget
Returns a list that contains the header-cell child object of every grid-row in every row-section of grid-widget (a grid-widget). The properties of each of these objects can be modified to specifically modify the drawing style of the header cell of each row.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: grid-widget
This operator works exactly the same as column-header-defaults, except for grid-row and row-section objects rather than grid-column and column-section objects. See column-header-defaults for full information.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
Generic Function, cg package
Arguments: class-grid
Returns the font that is used in the header cell at the left of each grid-row of a class-grid. The value may be set with the row-header-font initarg or by calling (setf row-header-font).
Generic Function, cg package
Arguments: class-grid
Returns the horizontal-justification of the text in row header cells in the leftmost column of a class-grid. The value may be set with the row-header-justification initarg or by calling (setf row-header-justification).
The value may be :left, :center, or :right.
Generic Function, cg package
Arguments: class-grid
Returns the type of value to display in each row header cell in the leftmost column of a class-grid. The value may be set with the row-header-value-type initarg or by calling (setf row-header-value-type).
The value may be one of the following symbols:
nil - the column of row header cells will not be present at all.
:index - the rows will simply be numbered from 1 to the number of rows. Changing the order of the rows will still leave the rows numbered sequentially from 1 upward.
:pretty-name - if a primary-name-slot has been established for the edited-class of the class-grid, then the pretty name derived from that slot (and optionally the secondary-name-slot) will be used. Otherwise the rows will be numbered as with :index.
:oid - if the edited-class of the class-grid is a persistent (AllegroCache) class, then the OID of each instance will appear in its row header cell. Otherwise the rows will be numbered as with :index.
Generic Function, cg package
Arguments: class-grid
Returns the section-size (width in pixels) of the column of row header cells at the left of a class-grid. The value may be set with the row-header-width initarg or by calling (setf row-header-width).
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns the number of blank pixels between the array of images in a lamp widget and the label strings alongside the rows. The value may be specified at creation time with the row-label-margin initarg, or anytime later by calling (setf row-label-margin). This value is used only when the value property of the lamp widget is an array.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns the number of blank pixels by which to shift the label strings downward alongside the rows of images in a lamp widget. The value may be specified at creation time with the row-label-offset initarg, or anytime later by calling (setf row-label-offset). This value is used only when the value property of the lamp widget is an array.
This property may be used as a fudge factor to make the labels appear as aligned as possible with the lamp images, adjusting for the internal leading of the widget's font.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns the side on which the row-labels of a lamp widget are displayed. The value may be one of the keyword symbols :left or :right. The value may be specified at creation time with the row-label-side initarg, or anytime later by calling (setf row-label-side). This value is used only when the value property of the lamp widget is an array.
Generic Function, cg package
Arguments: lamp
A property of the lamp widget. This generic function returns a list of strings to display beside the rows of images in a lamp widget. The value may be specified at creation time with the row-labels initarg, or anytime later by calling (setf row-labels). This value is used only when the value property of the lamp widget is an array.
The first string is displayed by the uppermost row of images, the second string by the second row, and so on until there are no more rows or strings. The strings are displayed on the row-label-side of the lamp images, with row-label-margin blank pixels in between.
Generic Function, cg package
Arguments: calendar-widget
The number of extra blank pixels to add between adjacent rows in a calendar widget.
See also the calendar class and the function ask-user-for-date.
Function, cg package
Arguments: grid-widget section-name
Returns a row-section object given its name and the grid that it is on.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: grid-widget
Returns the horizontal sections of the argument grid-widget. row-sections is a property of the grid-widget class.
Generic Function, cg package
Arguments: class-grid
Returns whether the user can interactively change the order of grid rows in the body of a class-grid (by clicking and dragging them). The value may be set with the rows-are-movable initarg or by calling (setf rows-are-movable).
Generic Function, cg package
Arguments: class-grid
Returns whether the user can interactively change the height of grid rows in the body of a class-grid (by clicking and dragging their lower borders). The value may be set with the rows-are-resizable initarg or by calling (setf rows-are-resizable).
Generic Function, cg package
Arguments: class-grid
Returns whether the user can interactively select rows in the body of a class-grid (by clicking them or pressing the spacebar when they have the keyboard focus). The value may be set with the rows-are-selectable initarg or by calling (setf rows-are-selectable).
Generally this is useful only when the user is allowed to delete the selected rows.
Generic Function, cg package
Arguments: tab-control
Returns the height occupied by all of the tab rows of a tab-control control. Controls should be placed onto the tab-control below this distance from the top of its dialog-item-box to prevent them from overlapping the tabs.
Generic Function, cg package
Arguments: rich-edit
Returns the name of the rich-edit-ruler control that is attached to rich-edit, which must be an instance of the rich-edit control class, if any, and nil otherwise. This property should be set only when creating the rich-edit by passing the name of the rich-edit-ruler control as the value of the :ruler initarg to make-instance.
When attaching a ruler interactively by dragging it onto a rich-edit control on a form, this property is set automatically.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: project-or-app
Returns whether a console window with an always-active Lisp listener will be present in the standalone application that is generated for a project. This ide:project property has an effect only on the Windows platform, because that is the only platform that uses a console window.
In the IDE, run-with-console is a property of a ide:project, and in a generated application it is a property of the app object. The setf of this function may be called to set the value programmatically, though typically you would set the value interactively by using the Run with Console check-box on the Advanced tab of the Project Manager dialog.
If the value is nil, as it is by default, then a console window may still exist in the standalone application, but it will initially be hidden. It will also have an active read-eval-print loop only if an error occurs or if the user presses the Break key.
If the value is true, then the console window will appear when the standalone application is run (though initially behind the project's main window if it has one), and its read-eval-print-loop will be active at all times. This is implemented by using multiple processes in the standalone app, which would otherwise use only a single process unless the application creates processes itself.
The console window will exist in a standalone application (on the Windows platform only) if either this property is true or if the :allow-runtime-debug option is included in the ide:build-flags property of the project (which is normally set by checking the Enable Debugging of Runtime Errors widget on the Build tab of the Project Manager).
Macro, cg package
Arguments: function &rest args
This macro had an effect only on GTK, which is no longer supported. It no longer has any effect, and any uses of it in application code could be removed.
Generic Function, cg package
Arguments: character-format
Returns the value of the same-bold property of a character-format object. The value is either t or nil. t is returned if all text is bold or all is not. See bold.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: character-format
Returns the value of the same-color property of a character-format object. The value is either t or nil. t is returned if all text has the same color. See color.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: character-format
Returns the value of the same-face property of a character-format object. The value is either t or nil. t is returned if all text has the same face. See face.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: character-format
Returns the value of the same-italic property of a character-format object. The value is either t or nil. t is returned if all text is italic or all is not. See italic.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: character-format
Returns the value of the same-point-size property of a character-format object. The value is either t or nil. t is returned if all text is the same size. See point-size.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: character-format
Returns the value of the same-underline property of a character-format object. The value is either t or nil. t is returned if all text is underlined or no text is underlined (that is, the underlining is the same for all text). See underline.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: window
This function is used by the File | Save As menu-item of the default menu-bar that may be interactively attached to a form. In the IDE, it demonstrates a typical "Save As" command for saving a text file but this function is not available in a runtime image. A custom application that implements a "Save As" command will need to supply its own code for such a command instead, but it may be useful to model after the default menu-bar's example. Here is the code for the save-as-text-file example (note: this code changed between release 6.2 and release 7.0):
(in-package :cg)
(defmethod save-as-text-file ((window basic-pane))
;; Called by the default "Save As" menu-item added to a form.
(let* ((selected-window (selected-window window)))
(when selected-window
(save-text-file-2
selected-window nil (file selected-window)))))
(defmethod save-text-file-2 ((window basic-pane)
&optional pathname old-pathname)
(declare (ignore pathname old-pathname))
(warn "The selected window does not know how to do a save."))
(defmethod save-text-file-2 ((window text-edit-window)
&optional pathname old-pathname)
(unless pathname
(setq pathname (ask-user-for-new-pathname
"Specify the new directory and filename."
:stream window
:initial-directory
(and old-pathname
(path-namestring old-pathname))
:initial-name (and old-pathname
(file-namestring old-pathname)))))
(when pathname
(let* ((text-edit-pane (frame-child window)))
(save-file text-edit-pane pathname)
(setf (file text-edit-pane) pathname)
(setf (title window)(namestring pathname)))))See also new-text-editor, open-text-file, and save-text-file.
Generic Function, cg package
Arguments: text-edit-pane file
Saves the current text of a text-edit-pane to a file. text-edit-pane should be a text-edit-pane (for a rich-edit-pane, use rich-edit-save instead).
file should be a pathname or path namestring indicating where to save the file. If a file already exists at this location, it is replaced by the newly-saved file. (The existing file is backed up temporarily during the save, and if an error occurs then the original file is restored when the error is unwound).
On the Windows platform, the file typically will be written using the character encoding that load-file deemed the file to have, if load-file has been called on the text-edit-pane. See external-format-for-saved-files for more information.
In CG/JS mode, the file will be always be written with a UTF8 character encoding.
Compatibility note: In earlier releases, this function would invoke the file dialog if a file argument (which was optional) was not supplied. This is no longer done, primarily because there was no way to specify the various options of the file dialog (unless we copied all the paramaters of ask-user-for-new-pathname to save-file, which would be poor design). If an application wishes to call save-file with a user-specified file, it should now first call ask-user-for-new-pathname if needed, and then pass the returned file to save-file (unless nil was returned due to the user canceling the dialog). save-file used to (but no longer does) accept an allowed-types keyword argument (although this was not documented). If an allowed-types argument is desired, then it should be passed to ask-user-for-new-pathname instead.
Generic Function, cg package
Arguments: rich-edit-pane
Returns (or sets with setf) whether the argument rich-edit-pane will currently save its links into a .lin links file whenever rich-edit-save or rich-edit-save-as is called on it. Finding links can be slow, so you may want to have this property turned off when it's not really being used.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: pane &key path
Saves the current links of pane to path. path defaults to the file of pane except with the extension changed to .lin. This is done automatically when rich-edit-save is called, assuming that save-links has been turned on for pane. save-links-file may be useful for applications that do not use rich-edit-save and rich-edit-open to save and restore rich text.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: pixmap filename
An alternative to save-pixmap that is probably more convenient for most uses is the function import-pixmaps.
Creates a file containing Lisp source code for recreating a pixmap. The source code file (or the fasl file that results from compiling it) may be loaded in a later invocation of Lisp or a runtime application in order to recreate the pixmap.
Alternately, the generated code may be copied into an application's source code and modified in order to assign the pixmap to a global variable or to return it from a function, for example. This allows the pixmap to be embedded in the image file of a runtime application so that neither the original .bmp file nor the Lisp file created by save-lisp-pixmap needs to be distributed with an application.
Lisp pixmaps can be loaded with load-lisp-pixmap.
filename is a pathname or path namestring naming the file to be created. If a file already exists at this path, it is replaced by the newly created file.
pixmap is the pixmap object to be saved in the file.
There are a couple of alternate ways to embed code for recreating a pixmap in an application's source code, which may be handier than calling save-lisp-pixmap. One way is to evaluate a form such as
(pprint (recreation-code my-pixmap)) in the Debug Window, and then to simply cut and paste the printed source code into the application.
Another way is to inspect a pixmap object, go to the internals tab, and click on the button at the right side of the top line to invoke the "extended editor" for the whole pixmap. The modal editor window that pops up will contain the recreation code for the pixmap, which could then be copied and pasted into application source code. (Though the extended editor is read-only in this case, you can still copy the text from it.)
Note that pixmaps used in controls on forms are automatically saved as Lisp source code into the .bml file for the form, using a similar technique. So there is no need for an application to embed these pixmaps explicitly.
save-lisp-pixmap is rather slow for large pixmaps, so it may be preferable to distribute .bmp files with an application if managing the .bmp files is not problematic. See save-pixmap.
Generic Function, cg package
Arguments: object-editor
Returns whether an object-editor dialog will automatically call object-editor-save whenever the keyboard focus is moved from the object-editor, such as by selecting a sibling window or another application. The value may be set at creation time with the save-on-clear-focus initarg, or any time later by calling (setf save-on-clear-focus).
The default value is true to avoid letting the user lose edits when they switch to another window and neglect to return. A drawback is that object-editor-revert cannot be used on the current-instance after switching to another window and back.
Generic Function, cg package
Arguments: object-editor
Returns whether an object-editor dialog will automatically call object-editor-save whenever the user modifies the value of any slot-editing widget in the object-editor. The value may be set at creation time with the save-on-new-widget-value initarg, or any time later by calling (setf save-on-new-widget-value).
The default value is nil to allow the user to revert from widget edits before a save is done in some other way. Setting this property to true basically means that object-editor-revert will never do anything.
Generic Function, cg package
Arguments: pixmap filename &key (quality 100)
Saves a pixmap to a new file. Any pixmap can be written as a BMP, PNG, JPEG, TIFF, or GIF file. Note GIF files are supported only on the Windows platform.
pixmap is the pixmap to save. It may have been loaded from a file with load-pixmap, or copied from the screen with get-pixmap, or created programmatically from a Lisp array of pixel values (see cg-pixmaps.html).
filename is the path of the file to create. It can be either a pathname or a path namestring. If the file already exists it will be replaced.
quality is an integer between 0 and 100 inclusive, specifying a tradeoff value between image quality and file size. It is used only for jpeg files (though that possibly could change with enhancements to the encoders that are in the underlying windowing systems). The default value is 100, which means the highest quality and largest file size.
The kind of pixmap file that's written is determined by the pathname-type of the filename argument, which should be either bmp, png, jpeg, jpg, tiff, tif, or gif. BMP files are uncompressed and therefore the largest, while PNG files are smaller, and JPEG files (even when quality is 100) are typically smaller still.
One known unsolved problem on Windows is that it doesn't work to load a non-bmp pixmap from a file and then save it as a bmp file if you passed the use-gdi-plus argument to load-pixmap as true.
A pixmap could alternately be saved to a file as Lisp source code with save-lisp-pixmap.
See also cg-pixmaps.html.
Generic Function, cg package
Arguments: text-edit-pane
Use of this option is deprecated. It had been a property of the multi-line-editable-text widget and the text-edit-pane window.
The value defaults to true, which means that the widget will retain the same selected text after the keyboard focus moves away from it and back to it. Specifying nil instead is no longer officially supported, though for backward compatibility it will still pass the option on the Windows platform to select all text when you tab to the widget, even though Microsoft stopped documenting this option some time ago.
Function, cg package
Arguments: string pathname-or-namestring
Creates a file at pathname-or-namestring containing string. This may be used for either a plain-text or rich-text string.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: window
This function is used by the File | Save menu-item of the default menu-bar that may be interactively attached to a form. In the IDE, it demonstrates a typical "Save" command for saving a text file but this function is not available in a runtime image. A custom application that implements a "Save" command will need to supply its own code for such a command instead, but it may be useful to model after the default menu-bar's example. So here is the code for the save-text-file example (note that this code changed between the 6.2 and 7.0 releases):
(in-package :cg)
(defmethod save-text-file ((window basic-pane))
;; Called by the default "Save" menu-item added to a form.
(let* ((selected-window (selected-window window)))
(when selected-window
(save-text-file-2
selected-window (file selected-window)))))
(defmethod save-text-file-2 ((window basic-pane)
&optional pathname old-pathname)
(declare (ignore pathname old-pathname))
(warn "The selected window does not know how to do a save."))
(defmethod save-text-file-2 ((window text-edit-window)
&optional pathname old-pathname)
(unless pathname
(setq pathname (ask-user-for-new-pathname
"Specify the new directory and filename."
:stream window
:initial-directory
(and old-pathname
(path-namestring old-pathname))
:initial-name (and old-pathname
(file-namestring old-pathname)))))
(when pathname
(let* ((text-edit-pane (frame-child window)))
(save-file text-edit-pane pathname)
(setf (file text-edit-pane) pathname)
(setf (title window)(namestring pathname)))))See also new-text-editor, open-text-file, and save-as-text-file.
Generic Function, cg package
Arguments: texture texture-info filename
Creates a device-independent bitmap file (whose filename typically has extension .bmp) from a texture and an associated texture-info structure.
The arguments are as follows. texture is a two-dimensional array of pixel values. texture-info is a texture-info structure which is used to determine the colormap and bits-per-pixel for the texture file. The bits-per-pixel can be larger than is reflected by the element-type of the array; thus you can save a 4-bits-per-element array as an 8-bits-per-pixel .bmp file. filename is a string naming the complete pathname of the bitmap file to be created. This filename should typically have extension .bmp.
Generic Function, cg package
Arguments: printer
Takes a printer stream and returns a number indicating the scaling factor that the end user has selected on the print job dialog that was invoked when the printer stream was opened. This number indicates the scaling that the printer driver itself will perform, and so the application does not need to do the scaling itself. This scaling factor is independent of scaling that can be achieved in common graphics by call (setf stream-units-per-inch) (see stream-units-per-inch) on the printer stream.
If the print job dialog for the particular printer does not support scaling, the return value may be 0 but this has not been tested with many printers.
scale is a property of the printer class.
This function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream using the :scale initarg, but some printers may ignore this value.
Generic Function, cg package
Arguments: stream position-or-box
Argument stream should be a cg-stream. For a stream that has the scaling-stream mixin, destructively modifies position-or-box from scaled units to pixel units. For other streams, simply returns the position or box that was passed.
Generic Function, cg package
Arguments: system
Returns the screen object, which is the parent of all top-level windows, when called on *system*. So the calling form is this:
(screen *system*)See also the class screen, which is the class of the single screen instance.
Function, cg package
Arguments:
If Windows is running in non-true-color mode (that is, if a screen depth less than 24-bits-per-pixel has been selected by the end user in the Display area of the Windows Control Panel), then this function returns a vector of rgb objects reflecting the current set of colors that is currently mapped into the system palette (by whatever combination of applications has mapped them into the system palette). If Windows is running in true-color mode, then nil is returned (since there is no system palette in that case).
Generic Function, cg package
Arguments: window width height depth
This generic function is called whenever a change is made to the screen resolution while the application is running. The screen resolution is the pixel coordinate range that fits onto the screen, and within which an application needs to fit its top-level windows.
An application should not call this function, but it may add methods for doing side effects such as moving or resizing application windows to fit the new screen resolution.
window is a top-level window (one whose parent is the screen). This function will be called once for each top-level window.
width is the new screen width in pixels.
height is the new screen height in pixels.
depth is the new screen bits-per-pixel.
The IDE's ide:move-ide-windows-on-screen-resize configuration option uses this feature to reposition IDE tool windows.
In Windows desktop mode, the screen resolution can change due to the user changing system-wide settings to scale everything by 125% (for example), or connecting via Remote Desktop from another machine, or swapping in a different monitor, or changing the effective resolution of the current monitor.
In web browser mode, the logical screen is the interior of the browser tab where the app is running. A new screen resolution therefore can be due to the user resizing the whole browser window, or adding or removing a browser toolbar (for example).
A special case in web browser mode is the browser's commands to zoom (or scale) the whole web page, typically zooming in to read text more easily or zooming out to fit more content into view. In CG code, zooming in looks just like the screen getting smaller, and zooming out looks just like the screen getting bigger. So an application can respond in the same way, without needing to know that it's actually a zoom that was done. The usual browser keystrokes for zooming are in a project's browser-keychords property by default to allow that built-in browser behavior. See the Browser Keychords widget on the CG/JS tab of the Project Manager dialog. Those keystrokes are Control+Plus, Control+Minus, and Control+Zero, except using the Command key on the Mac instead of the Control key.
Generic Function, cg package
Arguments: stream position-or-box
The name of this function has been changed to device-to-dialog-units. See the description of that function for details. The symbol screen-to-dialog-units continues to name that function as well, for backward compatibility.
Generic Function, cg package
Arguments: stream position-or-box
Modifies position-or-box, which is regarded as relative to the exterior upper left corner of the screen, so that it is relative to the interior upper left corner of window.
Generic Function, cg package
Arguments: object
Returns true if object is an instance of the screen class, and returns nil otherwise. This may be useful for determining whether the owner or parent of a window is the screen rather than a window, for example.
Currently there is only a single screen object, but a possible future enhancement would be the support of multiple monitors, where there is a screen object for each monitor. In that situation, calling screenp would be preferable to an expression such as (eq my-stream (screen *system*)) (see screen and *system*).
See also windowp.
Function, cg package
Arguments: window offset &key delay-redraw
Scrolls window by offset which must be a position object (see make-position) indicating the amount to scroll by in the x and y directions. Redrawing is delayed if the delay-redraw keyword argument is true. Returns the actual amount of scrolling achieved as a position, or nil if no scrolling was done. See also scroll-to.
This function is called automatically by user-scroll when the user clicks on the scrollbar of a regular window or a lisp-widget-window (but not for an os-widget-window, which handles its scrolling internally).
Keystrokes do not automatically scroll windows by default. Keyboard scrolling can be set up by writing a virtual-key-down method that calls this function, or more simply by using the handle-scrolling-keys property.
Generic Function, cg package
Arguments: window box offset
Scrolls (in the sense described below) the contents of box on window by offset (which is a position, see make-position, whose x and y components say how far to scroll in the x and y directions). Pixels moved out of box are lost. Background texture is moved into box to replace pixels that have moved. box must be a box, see make-box.
This function does not do a true scroll. It simply copies a rectangular portion of the window's contents to another place in the window, and is therefore like a special case of copy-stream-area.
Generic Function, cg package
Arguments: list-view &optional vertically-only
Scrolls list-view as needed to make the current index visible. Scrolling is vertical only (so the row containing the current index is visible) if the keyword argument is true.
Function, cg package
Arguments: window
This works like mouse-move-filter, except for scroll-to events. This typically applies when the user is dragging a scroll-bar of a window.
Generic Function, cg package
Arguments: window type direction
This generic function is called to determine the amount by which a regular (non-widget) window should be scrolled when the user clicks on the window's scrollbars. Any method should return the scroll amount, measured in pixels. This function is called whenever the user clicks on the arrows or body of the scrollbars, but not when they drag the scroller box.
This function is called only when running in Windows desktop mode. When running in CG/JS mode, scrolling gestures in windows will scroll by the amount that the web browser always uses, and there is no way to control that in CG.
window is the window being scrolled.
type is either :line (if the user has clicked on a scrollbar arrow) or :page (if the user has clicked in the scrollbar body).
direction is either :vertical (if the user has clicked on a vertical scrollbar) or :horizontal (for a horizontal scrollbar).
Here are the default methods. They cause line scrolling to scroll by one text line, and page scrolling to scroll by one text line less than a full page. An application can add methods as needed to override these defaults.
(defmethod scroll-increment ((window basic-pane)(type (eql :line))
(direction (eql :vertical)))
(line-height window))
(defmethod scroll-increment ((window basic-pane)(type (eql :line))
(direction (eql :horizontal)))
(space-width window))
(defmethod scroll-increment ((window basic-pane)(type (eql :page))
(direction (eql :vertical)))
(i- (visible-box-height window)
(line-height window)))
(defmethod scroll-increment ((window basic-pane)(type (eql :page))
(direction (eql :horizontal)))
(- (visible-box-width window)
(space-width window)))Generic Function, cg package
Arguments: chart-widget
Returns the value of the scroll-line-items property of a chart-widget. The value may be set at creation time by passing the :scroll-line-items initarg, or any time later by calling (setf scroll-line-items).
scroll-line-items is the number of chart items by which a chart-widget will scroll along its item axis when the user presses an arrow key. The value should be a positive integer. The default value is 1, so that the widget will scroll by one chart item each time an arrow key is pressed.
See also scroll-page-portion and scroll-on-drag.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the scroll-on-drag property of a chart-widget. The value may be set at creation time by passing the :scroll-on-drag initarg, or any time later by calling (setf scroll-on-drag).
scroll-on-drag is a boolean value indicating whether the user can scroll a chart-widget along its item-axis by clicking and dragging the chart body. The default value is t.
Mouse scrolling is done by clicking down anywhere in the body of the chart and then dragging along the direction of the item-axis. The chart contents will move by an amount equal to the mouse movement distance multiplied by the scroll-on-drag-factor property.
Even when this property is nil, a chart-widget can still be scrolled with the PageUp, PageDown, and arrow keys. See scroll-line-items and scroll-page-portion.
A chart is never scrollable if its fit-chart-items property is true, because it then squeezes all data into the viewable area.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the scroll-on-drag-factor property of a chart-widget. The value may be set at creation time by passing the :scroll-on-drag-factor initarg, or any time later by calling (setf scroll-on-drag-factor).
scroll-on-drag-factor is the number of pixels by which a chart-widget will scroll along its item-axis for each pixel of mouse movement during a drag scroll. The value should be a positive real number. The default value is 3, to cause the chart to scroll three times as far as the mouse moves.
This property is used only when the scroll-on-drag property is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the scroll-page-portion property of a chart-widget. The value may be set at creation time by passing the :scroll-page-portion initarg, or any time later by calling (setf scroll-page-portion).
scroll-page-portion is the portion of a whole "page" by which a chart-widget will scroll along its item-axis when the user presses the PageUp or PageDown key. A "page" means the length of the item-axis, so a value of 1 would cause a keystroke to scroll all of the current contents off to reveal contents that lie just out of view.
The value should be a positive real number, and generally should be no greater than 1 to be useful. The default value is 0.7 so that a portion of the pre-scrolled contents remains in view after a page scroll for context.
See also scroll-line-items and scroll-on-drag.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: grid-widget
Returns the number of pixels by which a grid-section of the specified grid-widget will automatically be scrolled at each increment as the user drags a grid-subsection to a new position among its siblings. (A grid-subsection is either a grid-column or a grid-row.) The setf of this function may be called to modify the value for a particular grid-widget, or the value can be specified at creation time by passing a scroll-parent-section-distance initarg to make-instance.
If the scroll-parent-section-while-dragging property of the grid-widget is an integer, then this is the number of pixels that the parent section will scroll (when possible) each time that number of milliseconds has passed. If that property is any other true value, then this is the number of pixels that the parent will scroll for each pixel past the parent section's boundary that the user has dragged the subsection. The default value is 4, to scroll by four pixels at a time.
Generic Function, cg package
Arguments: grid-widget
Returns whether any scrollable grid-section of the specified grid-widget will automatically scroll as needed when the user drags a grid-subsection past a boundary of its parent grid-section. (A grid-subsection is either a grid-column or a grid-row.) The setf of this function may be called to modify the value for a particular grid-widget, or the value can be specified at creation time by passing a scroll-parent-section-while-dragging initarg to make-instance.
When enabled, this option will scroll additional subsections of the parent section into view as the user drags a subsection, so that they can drop the subsection between siblings that were not initially visible.
The value can be one of the following:
nil, meaning no automatic scrolling is done. The user can still drag a subsection outside of the boundaries of the parent section and then drop it, but they won't be able to see where the subsection is being dropped amoung its siblings until the drop is done.
An integer, which indicates a number of milliseconds. Each time that number of milliseconds elapses, the parent section will scroll farther (if possible) by the scroll-parent-section-distance of the grid-widget. If the value is less than 10, then 10 will be used due to the minimum resolution of timers. The default value is 20, to scroll farther every 20 milliseconds.
Any other true value, then the parent section will be scrolled by the distance that user has dragged past the section's boundary, multiplied by the scroll-parent-section-distance of the grid-widget.
Generic Function, cg package
Arguments: window-or-object
Returns the position to which window-or-object has been scrolled relative to the page top left. To scroll a window to a new position, call scroll-to or scroll.
scroll-position may also be called on a grid-section, where the returned value is an integer rather than a position object. For a grid-row-section the value is a vertical scroll distance, and for a grid-column-section it is a horizontal scroll distance.
The scroll-position of a chart-widget is also a non-negative integer rather than a position object, since a chart will scroll only along its item-axis. The default value is zero, with the earliest chart data in view. (setf scroll-position) may be called to scroll a chart-widget to a particular place programmatically; passing a value of :end will scroll the widget to the very end of its data. See also scrolled-to-end and scrolled-to-end-maintained.
See also nscroll-position.
Generic Function, cg package
Arguments: window
Returns two values indicating the width and height of the scrollable page of window. The values exclude the area that is visible within the window (i.e. the visible-box-width and the visible-box-height). So a window that has exactly nothing scrolled out of view would have a scroll-range of zero, zero.
An application may override the default method of this and several other generic functions in order to implement a custom scrolling scheme that scrolls by logical picture objects rather than by pixels. See the source code of the example entitled 'Scrolling by arbitrary objects rather than pixels' on the Examples tab of the Navigator dialog for a complete example. More on this point and a list of the relevant generic functions can be found on the horizontal-scroll-bar and vertical-scroll-bar pages.
Function, cg package
Arguments: grid-widget grid-section scroll-pos
This function scrolls a grid-section programmatically. The arguments are:
grid-widget is the grid that contains the section to be scrolled.
grid-section is the grid-row-section or grid-column-section of grid-widget that is to be scrolled.
scroll-pos is a non-negative integer indicating the position to which the section should be scrolled. For a grid-row-section, this is the number of pixels that will be scrolled off the top edge of the section, and for a grid-column-section it is the number of pixels that will be scrolled off the left edge.
A scroll-pos of zero scrolls a section to its beginning, which will display the left end of the subsections of a column-section or the top end of the subsections of a row-section. scroll-pos may be specified as the value of most-positive-fixnum (or other large integer) to scroll the section exactly to its end (with the last subsection right-aligned with the end of the section), because a grid section is guaranteed not to scroll past either end of its contents.
To scroll a grid-row to the top of a grid-row-section or a grid-column to the left of a grid-column-section, pass the edge-position of the row or column to scroll-section.
The following example may be run when the "Employee Information" window still exists after running the "Employee Chart" example on the Examples tab of the Navigator dialog. This code will find that example grid and scroll its "main" column section programmatically. First the section will scroll to its beginning (with the "Full Time?" column left-aligned), then scroll explicitly to the "Inspect" column, and then scroll to the end of the section. This is done four times, waiting a second at each scroll position.
(let* ((window (find-window :employee-chart))
grid column-section inspect-column-position)
(unless window
(error "Couldn't find the Employee Information example window. ~
Run the Employee Chart example and try again."))
(select-window window)
(setq grid (find-component :employee-grid window))
(setq column-section (column-section grid :worksheet))
(setq inspect-column-position (edge-position
(subsection column-section :inspect)))
(dotimes (j 4)
(scroll-section grid column-section 0)
(sleep 1)
(scroll-section grid column-section inspect-column-position)
(sleep 1)
(scroll-section grid column-section most-positive-fixnum)
(sleep 1)))See section-scrolled on how to be notified whenever a grid-section is scrolled either programmatically or interactively.
Function, cg package
Arguments: grid-widget grid-section subsection &optional count
Scrolls subsection only as far as necessary to bring it totally within its section.
Generic Function, cg package
Arguments: text-edit-pane &key (lines-of-padding 0)(above t)(below t))
Scrolls a text-edit-pane vertically so that the text cursor is scrolled into view. It scrolls farther than needed by lines-of-padding, so that there are at least that many lines of text visible both above and below the text cursor for context (when possible). If the text cursor is currently scrolled off the top of the window, then it will be scrolled into view only if above is true. Similarly, if the text cursor is currently scrolled off the bottom of the window, then it will be scrolled into view only if below is true.
Generic Function, cg package
Arguments: window position &key delay-redraw
Scrolls window to position and updates the position of the slider in the scrollbar. Returns the new scroll position. Redrawing is delayed if the keyword argument delay-redraw argument is true. position must be a position (see make-position).
An application may override the default method of this and several other generic functions in order to implement a custom scrolling scheme that scrolls by logical picture objects rather than by pixels. See the source code of the example entitled 'Scrolling by arbitrary objects rather than pixels' on the Examples tab of the Navigator dialog for a complete example. More on this point and a list of the relevant generic functions can be found on the horizontal-scroll-bar and vertical-scroll-bar pages.
See also scroll-window-to-middle which scrolls a window so equal amounts are scrolled off the left and right and the top and bottom.
Function, cg package
Arguments: grid-widget grid-section subsection &optional count
Scrolls subsection so that it is flush left or top with its section.
Function, cg package
Arguments: window
If window is a child window, then calling this function will scroll its parent window as much as necessary for window to be fully visible in the interior of the parent window. If window is a top-level window, then nothing is done. For a discussion of parent and child windows, see see About child, parent, and owner windows in cgide.html.
function, cg package
Arguments: window
This convenience function scrolls a window as needed so that equivalent amounts are scrolled off the left and right sides, and off the top and bottom sides. This might be useful for initially centering a large diagram, for example.
This function simply calls scroll-to with a position at the middle of the scroll-range of the window.
Generic Function, cg package
Arguments: grid-widget section
Returns a box that indicates the region that the scrollbar of this grid-section occupies. This area is blank by default if the grid-section is not scrollable, and it may be useful to draw something else in this box in that case. The box is in the coordinates of the grid-widget's window (as returned by (window my-grid-widget)), and the drawing should be done on that window as well.
Generic Function, cg package
Arguments: grid-widget buttons section
Called when the user clicks one of the areas where a scrollbar would be if that section had a scrollbar. Modify this method to attach special behavior to those areas.
Generic Function, cg package
Arguments: window horizontal?
Returns a boolean value for whether a scrollbar of a window is currently present. If horizontal? is true then this is the horizontal scrollbar, and otherwise it is the vertical scrollbar.
Specifically, this will return true if the scrollbar has been enabled by the window's scrollbars property to appear when needed, and it currently is needed because the page-height or page-width of the window is greater than the interior-height or interior-width
Generic Function, cg package
Arguments: standard-object
Returns the value of the scrollbars property of the argument.
This property is unrelated to the scrollbar controls (horizontal-scroll-bar and vertical-scroll-bar) but instead refers to system-provided scrollbars for certain windows and controls. The value can be one of:
nil: no scrollbars
:horizontal: horizontal scrollbar only
:vertical: vertical scrollbar only
t, scrollbars in both directions
For windows other than controls, the page-height and page-width properties control the range of the scrollbars; for controls, the range is determined by the control's contents (except for the drawable control, which has explicit page-width and page-height properties like a window).
A combo-box cannot have a horizontal scrollbar, and so :vertical and nil are the only choices that appear in the inspector for this property, though t will still work to enable the vertical scrollbar.
A single-item-list or multi-item-list may have a horizontal scrollbar, but it will only appear if the multi-column-p property is true; this is a limitation in Windows. If a horizontal scrollbar is needed on an item-list that does not use multiple columns, an outline control could be used instead, using only top-level items in the range and turning off the draw-icons property to simulate an item-list.
This function is not setf'able. The scrollbars of a window or dialog-item must be established with the :scrollbars initarg when it is created, or using the inspector when designing a window or widget on a form.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the scrolled-to-end property of a chart-widget. The value may be set at creation time by passing the :scrolled-to-end initarg, or any time later by calling (setf scrolled-to-end).
scrolled-to-end is a boolean value indicating whether the item-axis of a chart-widget is currently scrolled to show the items with the highest indices (which typically were added most recently).
See also scroll-position and scrolled-to-end-maintained.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the scrolled-to-end-maintained property of a chart-widget. The value may be set at creation time by passing the :scrolled-to-end-maintained initarg, or any time later by calling (setf scrolled-to-end-maintained).
scrolled-to-end-maintained is a boolean value indicating whether modifying a chart-widget that is scrolled to the end will keep it scrolled to the end. The default value is t.
This property has an effect only when it is true and the widget happens to be scrolled to the end of its data. In that situation, if chart items are added or removed at the end of the data then the widget is scrolled automatically so that it is still scrolled to the very end of its data. This is also done if the chart-widget is resized (which typically would happen if its right-attachment or bottom-attachment is :right or :bottom and the user resizes the parent window).
See also scrolled-to-end and scroll-position.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: class-or-class-name
Returns the name of one of the slots of the specified class, which may be used to print instances of the class in a meaningful way in class-grids and object-editors. The value may be set at any time by calling (setf secondary-name-slot).
class-or-class-name should be either a class object or the name of a class.
The secondary name slot for a class is used only if the primary name slot has also been established. See primary-name-slot for more information.
Generic Function, cg package
Arguments: grid-widget section &optional include-border-p box
Returns a box or nil indicating where a grid section lies on the grid widget window, clipped according to grid boundaries and section boundaries.
When the specified section or subsection is scrolled completely out of view, this function returns nil. Otherwise it returns a box that reflects the visible part of the specified grid section.
grid-widget is the grid-widget containing the section.
section is the section whose box is being returned. This should be either a grid-row-section, grid-column-section, grid-row, or grid-column.
If include-border-p is true, then the area occupied by the border line at the right or bottom edge of the section is included in the returned box. Otherwise it is excluded.
box may be either a box (see make-box) or nil. If a box, then that box is modified and returned. If nil, a new box object is created and returned. Passing a scratch box avoids consing one that must be garbage collected.
See also cross-section-box and invalidate-whole-section.
Generic Function, cg package
Arguments: grid-subsection
Returns or sets with setf the value of the section-count property of the argument. This property determines the number of times that the grid-row or grid-column will be replicated. A replicated row or column will appear as multiple rows or columns, except that the format (size, font, etc.) is always the same for the whole set. And the whole set shares the same data-object (for rows) and data-reader (for columns) and so on. Some grid functions take row-number and column-number arguments, which identify the particular replication of the row or column object. A section-count of 1 indicates a "regular" non-replicated row or column. This is the default.
A replicated row or column may be useful when displaying a set of items that should look and behave exactly the same on a grid. For example, in the employee grid example the bar-chart section that displays a bar for each of the twelve months of the year is implemented as a single replicated grid-column with a count of 12. Internally, the 12 values are kept in a single list, and the column-number that is passed to various methods is used to reference a particular column's index within the list. The employee grid example can be found on the Examples tab of the Navigator dialog.
section-count is a property of the grid-subsection, grid-column, row-header-column, grid-row, and column-header-row classes.
Generic Function, cg package
Arguments: section
Returns the grid-widget of a subsection (row/column).
Generic Function, cg package
Arguments: grid-section new-scroll-pos old-scroll-pos max-scroll-pos
This generic function is called whenever a grid-section is scrolled, either interactively with the mouse or keyboard or programmatically by calling scroll-section. The default method does nothing, but applications may add section-scrolled methods if they need to know when grid scrolling occurs.
For example, an application could note when a grid-section has been scrolled to the end, and add new subsections at that time. Or it could compare the new-scroll-pos to the edge-position and section-size properties of the section's rows or columns to determine which rows or columns are now visible.
section-scrolled is not called when the grid is being created. Nor is it called if the application calls scroll-section with a new scroll position that is equal to the current scroll position of the section.
section-scrolled is called with the follwing arguments:
grid-section is the grid-row-section or grid-column-section that was scrolled.
new-scroll-pos is a non-negative integer indicating how far the section is now scrolled from its leftmost (for a grid-column-section) or topmost (for a grid-row-section) scroll position, in pixels.
old-scroll-pos is a non-negative integer indicating the scroll position just before the most recent scrolling movement. Note that if the user drags the scroll gadget, section-scrolled is called multiple times to reflect the multiple redisplays that are done to effect smooth scrolling, with old-scroll-pos being equal each time to the value of new-scroll-pos from the previous call.
max-scroll-pos is a non-negative integer indicating the scroll position when the section is scrolled all the way to the right or the bottom. There is no min-scroll-position argument because the minimum scroll position of a grid-section is always zero.
scroll-position can alternately be called on a grid-section to find its current scroll position at any time.
Function, cg package
Arguments: grid-section
Returns or sets with setf the "breadth" of a grid-column-section, grid-row-section, grid-column, or grid-row (of a grid-widget), in pixels. This is the width of a column or the height or a row. The setf will resize the section, making adjustments to other sections as well if their proportional properties are turned on. The size does not include the width of the border along the right or bottom side of the section, which is returned separately by border-width.
Generic Function, cg package
Arguments: tab-control rightward
Selects the tab of tab-control (which must be a tab-control) that is immediately to the left or right of the currently selected tab. This method would typically be called by keyboard shortcuts for selecting nearby tabs (as seen in some IDE dialogs when right-clicking a tab).
If rightward is true, then the tab on the right is selected, and otherwise the tab on the left is selected. If there are no further tabs in the indicated direction, then nothing is done.
Generic Function, cg package
Arguments: item-list
Returns the value of the select-on-multiple-characters property of an item-list (that is a single-item-list, or a multi-item-list) or an outline control. The value may be specified at creation time by passing the select-on-multiple-characters initarg to make-instance, or any time later by calling (setf select-on-multiple-characters).
This property provides an alternate way to select a value in an item-list or outline with the keyboard, where the user can type the first few characters of the value to select rather than the first character only. The value may be nil or true.
If the value is nil, which is the default, then the widget has the usual keyboard behavior where typing a character will always move to the next value in the list that begins with that character. If there are many values that begin with the same character, then the only way to select some of those values is to type that first character many times.
If the value is true, then the user can type additional characters beyond the first one in the string to be selected. As each additional character is typed, the first value that matches all characters that have been typed so far will be selected.
The associated property select-on-multiple-characters-time-limit specifies how many milliseconds must elapse after a keystroke for the substring that's being typed to be reset. To search for a different string just after another search, the user must wait that amount of time before typing a new sequence of characters.
For outline controls only: this property has an effect only when the select-on-typing property is true. When enabled, the user can press the Backspace key or Control-H to remove characters from the search string. The user can jump to additional matches by typing Shift-Space, or by pressing Enter if there is no default-button on the parent window. To be notified as the user types each character (also for an outline control only), see select-on-multiple-characters-callback. To skip some matching outline items, see select-on-multiple-characters-item-test.
This property is nil by default, mostly for backward compatibility.
Generic Function, cg package
Arguments: outline
Returns the value of the select-on-multiple-characters-callback property of an outline control. The value may be specified at creation time by passing the select-on-multiple-characters-callback initarg to make-instance, or any time later by calling (setf select-on-multiple-characters-callback).
This outline widget property has an effect only when the outline's select-on-multiple-characters property is true to allow finding an outline item by typing the first several characters of the string that it displays.
In that case, this property should be the name of a function that will be called whenever the search string has changed, or else nil to not call a function. The default value is nil. The callback function would typically be used to display the current search string somewhere near the outline. The function will be called each time the user types or erases a character, and also when the select-on-multiple-characters-time-limit expires.
The function should accept two arguments, which will be the outline control and the current search string. The search string argument will be a string when the user has typed or erased a character, or nil when the time limit has expired.
Generic Function, cg package
Arguments: outline
Returns the value of the select-on-multiple-characters-item-test property of an outline control. The value may be specified at creation time by passing the select-on-multiple-characters-item-test initarg to make-instance, or any time later by calling (setf select-on-multiple-characters-item-test).
This outline widget property has an effect only when the outline's select-on-multiple-characters property is true to allow finding an outline item by typing the first several characters of the string that it displays.
In that case, this property should be the name of a function that can be used to arbitrarily exclude some outline items from the search, or else nil to include all items in the search. The default value is nil. When the value is a function name, the function will be called whenever a matching outline-item is found. The function should accept a single argument, which is the matching outline-item. It should return true if the search should really match this outline-item, or nil to skip the item.
Generic Function, cg package
Arguments: item-list
Returns the value of the select-on-multiple-characters-time-limit property of an item-list (that is a single-item-list or a multi-item-list) control or an outline control. The value may be specified at creation time by passing the :select-on-multiple-characters-time-limit initarg to make-instance, or any time later by calling (setf select-on-multiple-characters-time-limit).
This property is used only when the associated property select-on-multiple-characters is true. In that case, the user can select a value in the list by typing the first few characters of the desired value. To select a second value in the same way, they must first wait this number of milliseconds so that the current search string is reset. The default value is 2000, requiring a two-second pause.
Generic Function, cg package
Arguments: dialog-item
Returns (or sets with setf) whether the outline-items of this outline will be selected when the user clicks on their pixmap icons to open them. Selecting an item means that it becomes the value of the component and is drawn in selection colors.
Note that clicking on the plus or minus symbol (or to its left) to open or close an outline-item will never select the clicked item, while clicking on the text of the item will always select it.
Generic Function, cg package
Arguments: item-list
Specifies which values will be selected after drag-and-drop does a drop onto the argument item-list widget.
The possible values are:
nil - The values that were already selected will continue to be the only selected values.
:new-only - The dropped values will be the only selected values.
:new-and-old - Both the dropped values and the values that had been selected will be selected.
Generic Function, cg package
Arguments: outline
Returns the value of the select-on-right-click property of an outline control. The value may be set at creation time by passing the :select-on-right-click initarg, or any time later by calling (setf select-on-right-click).
If this outline property is true, then right-clicking the widget will select the outline-item under the mouse before doing any other right-click behavior. If nil, it will not.
The default value is nil. It may be useful to set this property to true if, for example, you would like the user to be able to right-click an outline-item to both select that item and to pop up a menu whose commands would be applied to the selected item.
Other right-click behavior for an outline might be implemented in a mouse-right-down or shortcut-commands method for the associated outline-pane. If this property is true and there is a shortcut-commands method for the outline-pane, then the pop-up-menu will be positioned just below the selected outline-item.
Generic Function, cg package
Arguments: outline
Returns the value of the select-on-typing property of an outline control. The value may be specified at creation time by passing the select-on-typing initarg to make-instance, or any time later by calling (setf select-on-typing).
When this property is true, as it is by default, then the user will be able to select outline items by typing the starting characters of outline item labels. If select-on-multiple-characters is also true, then the first few or more characters of the desired item may be typed, and otherwise each typed character will jump to the next item whose label begins with that character.
Generic Function, cg package
Arguments: outline outline-item
Selects the specified outline-item in the specified outline, which means that the item will be highlighted and its value will be the value of the outline control. This is similar to calling (setf value) to set the value of the outline to be the value of the outline-item, but is more efficient due to not looking up the item from its value. And calling (setf value) is not a good idea if multiple outline-items have that same value, because the intended outline-item may not be the one that is found. So this function is generally preferable when you have a handle on the outline-item object.
Generic Function, cg package
Arguments: trackbar
Determines display and behaviors of the trackbar widget's tick-marked bar. If this property is true, the visible-range is displayed when the visible-range property is true.
The select-range property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :select-range initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
select-range is a property of the trackbar class.
Generic Function, cg package
Arguments: tab-control index
Selects a tab of tab-control (which must be a tab-control) that is in the stack of all tabs that have been selected. This method would typically be called by keyboard shortcuts for selecting recently-viewed tabs (as seen in some IDE dialogs when right-clicking a tab).
An index of 1 selects the tab that was selected most recently before the currently selected tab was selected, an index of 2 selects the tab that was selected just before that one, and so on. If index is greater than the number of tabs that have been selected so far, then nothing is done. An index of zero would select the currently selected tab, which is not useful.
Each tab may appear in the stack only once, reflecting its most recent selection; so if the user selected tabs A, B, C, B, and D in that order, then the stack would contain (D B C A), and so an index of 2 would select C while 3 would select A. When a tab is deleted, it is removed from the stack.
Generic Function, cg package
Arguments: grid-widget section subsection &optional invalidate-borders-p
Use of the function is deprecated. Use (setf selected) instead.
Selects a grid-row or grid-column in a grid-widget. A selected subsection is drawn in the selection colors as set up by the user in the Windows Control Panel. The selection status is used by the built-in grid-widget code only for the feature where all subsections that are both deletable and selected are removed from a grid-widget when the user presses the DELETE key while the grid-widget has the keyboard focus.
Generic Function, cg package
Arguments: window &optional recursive-p
Selects window and brings it to the front. recursive-p should be true if select-window is being called from a stream select-window function (that is, recursive-p should be nil when called directly). If window is shrunken it will be expanded. Sets focus if we are in the uppermost frame of window.
See also bring-window-to-front, which does that without selecting the window. If you are running a multi-threaded Common Graphics application in Windows desktop mode, then see set-foreground-window because this function (and bring-window-to-front) may not reliably move a window in front of windows that were created by other threads.
Generic Function, cg package
Arguments: grid-subsection
Returns the value of the selectable property of the argument. This property determines whether the grid-row or -column can be selected by clicking it. When a row or column is selected, it is drawn in the selection colors that the user has set up in the Windows Control Panel. Other than being drawn differently, the only special behavior that is built into a selected row or column is that all selected rows and columns that are also deletable will be deleted from a grid-widget if the user presses the DELETE key while the grid-widget has the keyboard focus. If other special behavior is desired for selected rows and column, it is up to the application to check the selected property of each row or column and treat it accordingly.
A selectable grid-row may be selected interactively only by clicking it in its cells that also lie in columns that are instances of row-selecting-column-mixin. Likewise, a selectable grid-column may be selected interactively only by clicking it in its cells that also lie in rows that are instances of column-selecting-row-mixin.
The setf of this function may be called at runtime to change the selectable status of a row or column.
selectable is a property of the grid-subsection, grid-column, row-header-column, grid-row, and column-header-row classes.
Generic Function, cg package
Arguments: object
Returns or sets with setf the value of the selected property of the argument.
object may be a menu-item. A selected menu-item will usually be displayed with a check mark next to its title when the menu is displayed. However, if its cluster property is true, then it will be displayed with a dot instead of check mark, and any other menu-items in the same cluster will be deselected automatically, making a set of menu-items act similar to a group of radio-button controls.
object may be a grid-row or grid-column (on a grid-widget) in which case the cells within in it are drawn using cell-selected-foreground-color and cell-selected-background-color rather than the usual cell-foreground-color and cell-background-color. The only other built-in behavior of a selected row or column is to be the object of delete-selected-subsections if it is called, but an application may choose to treat selected rows and columns in a custom way.
For a grid-row or grid-column (on a grid-widget), an application may call (setf selected) to programmatically select or deselect individual rows and columns; in addition, (setf selected) will be called automatically if the user left-clicks a cell whose grid-row or grid-column has a true selectable property and the intersecting column or row is an instance of row-selecting-column-mixin or column-selecting-row-mixin (respectively). (This is the default interactive behavior that could be overridden by a more specific cell-click method.) See also cell-selected, selectable, selected-reader, and deselect-all-subsections.
selected may also be called on an outline-item or a list-view-item, in which case it will return true if and only if the value of the associated outline or list-view currently is (or contains) the value of the outline-item or list-view-item. But an application should never call (setf selected) on an outline-item or list-view-item, and instead should call (setf value) on the associated outline or list-view control.
selected is a property of the grid-subsection, grid-column, row-header-column, grid-row, column-header-row, outline, list-view, and menu-item classes.
Generic Function, cg package
Arguments: window
Returns the class named by the selected text in window, if such a class can be determined. Returns nil otherwise. The selected text may be text containing the text cursor rather than highlighted text.
Generic Function, cg package
Arguments: window &optional only-consp
Returns a Lisp form that is considered to be selected in window and which may be acted upon by arbitrary commands that require a Lisp form. Returns nil if no such Lisp form can be derived.
Generic Function, cg package
Arguments: window
Returns an object (or a list of objects) that is considered to be selected in window. A user command could call this function on the selected-window to find a selected object on which to act.
A variety of methods of this generic function exist for returning selected objects in various kinds of windows. Additional methods could be added to return appropriate objects for specialized classes of application windows, though the build-in methods will often suffice. If no object is selected (including when no method is applicable to the specified window), then this function returns nil.
If text is selected, then the built-in methods often return that text directly as a string. See selected-string for more information on how a string to return is derived, especially in text-editing widgets. Otherwise some other arbitrary object or a list of objects may be returned.
You may sometimes want to make the menu-item for a command not be available when selected-object returns nil to indicate that there currently is no value for the command to act on. The generic function about-to-show-menu gets called automatically just prior to any pull-down-menu being displayed, to allow menu-items to be made available or not based on the current state. You could subclass the menu class and write about-to-show-menu methods on the subclasses that update the available property of menu-items accordingly.
Generic Function, cg package
Arguments: outline
Returns the outline-item that is currently selected in outline (which should be an instance of the outline class), or nil if no item is selected. If the multiple-selections property of the outline is currently true, then a list of zero or more outline-items is returned instead.
The value of this outline-item (or the list of the values of multiple items) is also the value of the outline itself. It is more efficient to pass an outline-item rather than its value to some outline functions.
The selected item is usually the same as the focused-outline-item, but not if scrolling with the keyboard has focused on an item that is in view without changing the selected item.
See also select-outline-item and focused-outline-item.
Generic Function, cg package
Arguments: printer
Returns whether the user has requested a range of pages to be printed.
selected-pages-p is a property of the printer class.
This function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Generic Function, cg package
Arguments: grid-column
Returns a function that returns whether each of the grid cells in a particular column of a grid-widget is currently selected, or else returns nil to determine the selection status in other ways (see cell-selected). The selected-reader function is a property of a particular grid-column, and is called once for each grid-row that intersects that column, to determine the selected status of the cell at the intersection of that row and column. The function should take one argument, which is the data-object of the grid-row. If the cell is currently considered to be selected, then the function should return true, and otherwise it should return nil. When selected, a grid cell is drawn in special colors, and the application may treat it in some special way.
This property value may be specified as either a function name symbol (which would be more debuggable), or a function object (which may be slightly faster, though probably insignificantly), or nil if this facility is not used. The default value is nil.
An application does not call the selected-reader function; it supplies the selected-reader function by calling (setf selected-reader) or by passing the :selected-reader initarg when calling make-instance to create a grid-column. The specified function is then called automatically by the system as needed.
Generic Function, cg package
Arguments: window
Returns a string that is considered to be selected in window, and which may be acted upon by arbitrary commands that require a string. nil (which is not a string) is returned if nothing is selected, even by the wide definition of selected text that is described next.
In a text-editing window or widget like a text-edit-pane or an editable-text widget, this function may return a string either when text is selected and when the text cursor is positioned within text but no text is selected. Thus, if the cursor is between the f and the first o of foo, then "foo" will be returned by selected-string even though no text is selected. But nil will be returned if the text cursor is in whitespace.
While some menu commands like copy-command will act on a word that a text-editing pane's text cursor is inside, others like cut-command will do nothing in that case.
Similarly, in some cases you may want to retrieve only text that is explicitly selected rather than the word that the text cursor is inside. In those cases, you should use get-selection followed by text-range. get-selection returns two integers indicating the beginning and the end of selected text. If the two values are equal, then no text is selected. Otherwise the values could be passed to text-range to retrieve the selected text rather than the enclosing word.
Generic Function, cg package
Arguments: window
Returns a symbol that is considered to be selected in window and which may be acted upon by arbitrary commands that require a symbol. The default method simply calls object-symbol on the selected-object of the window. Many menu commands in the development environment operate on the selected-symbol of the focused window. Returns nil if a symbol cannot be derived.
Function, cg package
Arguments:
Returns the color that will be used to paint the tab body of any tab-control when its button-style property is nil. If a Visual Style is in effect (see a-visual-style-is-active), this color will be a pale version of system-dialog-background-color, and otherwise it will be system-dialog-background-color itself.
To ensure that the background color of a widget on a tab-control matches the tab body color (regardless of whether a Visual Style is in effect), set its background-color property to t.
See ide:include-manifest-file-for-visual-styles for more information.
Generic Function, cg package
Arguments: parent-stream
Returns the child window of a window or the screen (as specified by the argument parent-stream) which is considered to be selected. Specifically, if the window specified by the argument currently contains the focus, then the child that also currently contains the focus is returned. Otherwise if the window has had the focus and the child window that most recently had the focus still exists and is in normal or maximized state, then that child is returned. Otherwise the frontmost window which is in normal or maximized state is returned.
This function returns a window even when Lisp is not the currently selected application. To return the selected top-level window only if Lisp is the currently selected application, use foreground-window.
See also get-focus.
Function, cg package
Arguments:
This simple function is provided as a convenience when invoking the various modal utility dialogs that are built into Common Graphics, such as pop-up-message-dialog or ask-user-for-choice-from-list. These functions have a stream argument for specifying the owner window for the modal dialog. The modal dialog will appear on this owner window, and the owner window and its other child windows will be disabled while the modal dialog is present.
selected-window-or-screen returns a stream that is typically suitable as the value of this stream argument. In fact, each of the utility dialog functions defaults its stream argument to the stream returned by this function. An application may find other uses for it as well.
Specifically, if there currently are any modal dialogs being invoked in the current process, then the one that is being invoked most recently is returned. (You can invoke a modal dialog on top of one that is already being invoked.) Otherwise, the currently selected top-level window is returned unless there is no such window, in which case the screen is returned.
Here is the definition of the function.
(defun selected-window-or-screen ()
(or (modal-window)
(selected-window (screen *system*))
(screen *system*)))See also modal-window, selected-window, screen, *system*.
Generic Function, cg package
Arguments: text-pane-or-control
If the notify-when-selection-changed property is turned on for a multi-line text pane or control, then whenever the text cursor changes position or different text is selected, the generic function selection-changed is called. An application may add selection-changed methods to see if it wants to respond to the text cursor movement. The single argument is the text pane or control. The return value is ignored.
The default for notify-when-selection-changed is nil for text-edit-pane and multi-line-editable-text, but is t for lisp-edit-pane to trigger parenthesis matching in the development environment. The notifications are turned off by default in case they slow down text editing interaction, though this is unlikely to be noticeable; when the property is turned on, the default selection-changed method does nothing for text-edit-pane and multi-line-editable-text.
Function, cg package
Arguments: window
This function should not be needed by applications, but it might come in handy anyway in certain situations for waking up the creation-process of the specified window more quickly than it would happen otherwise.
Generic Function, cg package
Arguments: widget-window
Text-editing widgets in JavaScript implement their own multi-level undo and redo, which CG could not reasonably implement. So CG/JS lets the web browser handle Control+Z and Control+Y (or Command+Z and Command+Y on a Mac) for those operations directly, rather than sending those keystrokes to the CG server as usual.
If an application instead needs to do some sort of custom undo and redo for a text-edit-pane or editable-text-pane subclass, then it should add a method to this generic function that returns true for that subclass. The browser will then send those keystrokes to the CG server for custom handling.
Generic Function, cg package
Arguments: window left top right bottom
Sets values describing how window's size changes when its parent is resized.
The possible values for left (specifying the left-attachment) and right (specifying the right-attachment) are:
The keywords :left, :right, or :scale. :left means maintain the same distance from the parent's left side as before the parent was resized -- if the distance was 30 pixels before, it is 30 pixels after the parent's resizing. :right means keep the distance to the right side constant. :scale means keep the ratio of the distances from the left and right sides constant -- if the side was half way between before, it is half way between after.
The possible values for top (specifying the top-attachment) and bottom (specifying the bottom-attachment) are:
The keywords :top, :bottom, or :scale. :top means maintain the same distance from the parent's top as before the parent was resized -- if the distance was 30 pixels before, it is 30 pixels after the parent's resizing. :bottom means keep the distance to the bottom constant. :scale means keep the ratio of the distances from the top and bottom sides constant -- if the side was half way between before, it is half way between after.
Macro, cg package
Arguments: b v
Use of this function is deprecated. Use setf and box-bottom instead.
Sets the bottom of box b to value v (which, like all dimensions, must be a positive fixnum). See box-bottom.
Macro, cg package
Arguments: b v
Use of this function is deprecated. Use setf and box-left instead.
Sets the left of box b to value v (which, like all dimensions, must be a positive fixnum). See box-left.
Macro, cg package
Arguments: b v
Use of this function is deprecated. Use setf and box-right instead.
Sets the right of box b to value v (which, like all dimensions, must be a positive fixnum). See box-right.
Boxes are made with make-box.
Macro, cg package
Arguments: b v
Use of this function is deprecated. Use setf and box-top instead.
Sets the top of box b to value v (which, like all dimensions, must be a positive fixnum). Boxes are made with make-box. See box-top.
Generic Function, cg package
Arguments: window &rest args &key (scope :all) face bold italic underline (style t) height color
This function is specific to Windows desktop mode and should not be called in CG/JS mode.
This function modifies the formatting of text in a rich-edit-pane. Depending on the value of the scope argument, the modification applies to all text or can be limited to selected text or text about the cursor.
window is a text-edit-pane and is typically a rich-edit-pane (a subclass of text-edit-pane). Note that neither a text-edit-window (typically the parent of a text-edit-pane) nor a rich-edit control are valid arguments to this function. Applying window to a rich-edit control results in a suitable argument, however.
scope is one of:
:all: changes all of the text in the pane.
:selection: changes the currently selected text, if any, and otherwise establishes the character format to use for newly typed text, if the text cursor is not moved in the meantime.
:word: changes the currently selected text if any, and otherwise changes the word surrounding the text cursor.
The default for scope is currently :all, but it arguably should be :selection. It is recommended that you always pass this argument so that your code will not need to change if the default is changed.
face and height are either as passed to make-font-ex or else nil for no change to that attribute. Note that height is interpreted as point-size rather than the usual common graphics pixel-size, due to lack of a means of converting this measurement for character formatting. Point-size is what appears in the font dialog.
color is an rgb color object (see make-rgb) or nil to not change the color.
style may be a list as passed to make-font-ex, or t for no change.
bold, italic, and underline can each be either :on or :off to change that attribute, or nil for no change; true values will override the style argument.
See also get-character-format.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Function, cg package
Arguments: chart-widget &key item-index object-index item-id object-id value from-value low-value high-value icon-size update-now
Establishes one or more of the values to display on a chart-widget for a single pairing of a chart item and a chart object. The return value is not defined.
(For example, if a line graph has a line for each bowler on a team, and a bowling score for each week, then each bowler is represented by a chart object while each week is represented by a chart item.)
An alternative to calling set-chart-value multiple times is to provide a chart-value-returner function that will be called as needed to return all of the chart's values. That approach is more efficient if you already have all of the chart's data stored somewhere such as in an array. The set-chart-value approach is somewhat more straightforward, and is more suitable if you are incrementally adding or modifying the data over time.
chart-widget is the widget to modify.
The first group of keyword arguments specify which chart item/object pair to modify.
item-index is the zero-based index of the chart item to modify, or the symbol :new to add a chart item just after the last existing chart item, or the symbol :last to modify the last existing chart item (that is, the one with the highest index), or nil to not specify an item index. If both item-index and item-id are nil, then item-index defaults to :new. If both item-index and item-id are true, then the item at item-index is used and its ID is changed to the specified item-id. If the chart is empty and item-index is :last, then it behaves like :new.
object-index is the zero-based index of the chart object to modify, or nil to not specify an object index. If both object-index and object-id are nil, then object-index defaults to zero. If both are true, then object-index takes precedence.
item-id is the arbitrary ID of the chart item to modify, or nil to not specify an item ID. If item-index is nil and item-id is true, then if there is an existing item whose ID is item-id then it will be modified, and otherwise a new item will be created just after the current last item, and its ID will be item-id.
object-id is the arbitrary ID of the chart object to modify, or nil to not specify an object ID. If object-index is nil and object-id is true, then if there is an existing object whose ID is object-id then it will be modified, and otherwise a new object will be created and its ID will be object-id.
(If there is no entry in the chart-objects property for the specified object-index or object-id, the chart-objects sequence is expanded to include such an entry.)
The next group of keyword arguments specify one or more values for the specified item/object pair. Any subset of these arguments may be passed, though the auxilliary values will have no effect until if and when the main value is specified for the same item/object pair. A value must always be either a real number to add a value to the chart, or else nil to remove a value from the chart. Existing values can be modified by respecifying them in further calls to set-chart-value.
value is the "main" value that is represented by the end of a bar in a bar graph or by line segment endpoints in a line graph.
from-value is the starting point of a bar in a bar graph. It defaults to the base-value of the bar-chart-view, which in turn defaults to zero.
low-value is an additional value that is typically somewhat lower than the main value. It is drawn according to the high-low-value-style of the chart-view, and is typically used for an error range.
high-value is an additional value that is typically somewhat higher than the main value. It is drawn according to the high-low-value-style of the chart-view, and is typically used for an error range.
icon-size is the size of the icon drawn at a particular data point on a line graph. The value is an integer to be used as the "radius" of the icon, measured in pixels. It is used only if the draw-icons property of the line-graph-view is true, and only if the icon-images property uses names of the built-in line-drawing icons (which are :circle, :square, :triangle, and :diamond) rather than pixmaps.
update-now indicates whether to display the new value now. If nil, then the widget is invalidated so that it will be redrawn to reflect the new value, but as usual not until all queued events are handled. This allows adding many values quickly, which will then be displayed once at the end. If true, then the chart will be redrawn immediately. This allows animating the incremental adding of values. (If a sleep or mp:process-wait occurs between the adding of incremental values, then the widget should still redisplay at those times without passing this argument as true.)
See chart-widget and also cg-chart-widget.html.
function, cg package
Arguments: left top width height
This function exists only on the Windows platform.
Moves and/or resizes the base Lisp's console window if it exists, and otherwise does nothing.
The four arguments should be integers and are measured in pixels. left and top indicate the new position of the top left corner of the console window relative to the top left corner of the screen. width and height are of course the new width and height of the window.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
Generic Function, cg package
Arguments: button-widget
Changes which button on a dialog is invoked by pressing the ENTER key (i.e. the default button). button must be an instance of class button already on a dialog (and it is that dialog whose default button is changed). An error is signaled if button is not on a dialog. The new default button will be drawn with a thick black border.
If the specified button is already the acting default button of its parent window, then nothing is done and nil is returned. Otherwise the specified button becomes the acting default button and a non-nil value is returned.
If a button of class default-button exists on the dialog, it will be the initial default button. This function is used to change the default button dynamically.
Note: following Windows environment practice, if the user gives the keyboard focus to any push button (the keyboard focus is shown by a thin dotted line about the button), that button is invoked by pressing ENTER or the Space Bar. This is regardless of whether it is the default button or not. ENTER will again invoke the default button when the keyboard focus moves away from any button.
Function, cg package
Arguments: dialog name value
Sets the value of a control on a dialog. The dialog argument can be either a dialog object or the name of a dialog. The name argument is the name of the control (on that dialog) whose value is to be set. The value argument is any value that could be used with (setf value) for the given control. value is returned.
Macro, cg package
Arguments: dialog &rest names-and-values
Sets the value of controls on a dialog. The dialog argument can be either a dialog object or the name of a dialog. The names-and-values arguments must be in pairs with the first argument being the name of a control and the second being the new value, which must be suitable as a value for the control. The values of all controls are modified as specified. Calling this function is similar to calling set-dialog-field for each name/value pair.
Function, cg package
Arguments: comtab events function
Adds a command to comtab for handling events, which may be either a single event or a list of events. If more than one event is given, function will be called if they occur sequentially, separated only by null events. function must take one argument, the stream in which the comtab event occurred.
The function argument may be either a function object (that accepts one argument), or a symbol that names a function that accepts one argument, or nil. Note that if a function object is used, then ide:comtab-report will not include the binding in its report, since it does not have a function name to report for the binding.
If function is nil, the effect is to remove any existing binding for the specified events from the comtab.
Each event in the events list is of the same form as a menu-item event-synonym. Refer to event-synonym for some examples of individual events.
Here are several of complete set-event-function examples:
Example 1
This example adds a command to the current editor comtab to make the gesture alt-shift-C scroll the current text line to the top of the editor pane. See ide:text-edit-comtab.
(defun scroll-line-to-top (window)
(setf (first-visible-line window)
(current-line-number window)))
(set-event-function *text-edit-comtab*
(list alt-key shift-key #\C)
'scroll-line-to-top)Example 2
This example adds a command to the current editor comtab to make the gesture alt-shift-comma scroll the current text line to the bottom of the editor pane. Unlike the first example, it uses a it uses a lambda expression rather than a named function. This example will do nothing if the window does not have enough lines of text to turn on the vertical scrollbar, and the window will not scroll upward past the starting scroll position where the first line of text is at the top.
(set-event-function *text-edit-comtab*
(list alt-key shift-key vk-comma)
(lambda (window)
(setf (first-visible-line window)
(- (current-line-number window)
(floor (interior-height window)
(line-height window))
-1))))Example 3
This more complete example includes creating a comtab and attaching it to a custom window. Since the window is not a text-edit-pane, where comtab-mixin is mixed in already, we must mix this class in ourselves.
We have used the plain "J" key here to draw a filled circle at the mouse, since we are not using a text window that would otherwise enter text. And F8 draws a circle outline at the mouse.
(in-package :cg-user)
(defclass my-window (comtab-mixin frame-window)())
(defun foo ()
(let* ((my-window (make-window :my-window
:device 'my-window
:parent (screen *system*)
:title "Press the F8 and J Keys"))
(my-comtab (make-instance 'comtab
:name :my-comtab
:inherit-from nil)))
(set-event-function
my-comtab vk-f8
(lambda (window)
(draw-circle window (cursor-position window) 12)))
(set-event-function
my-comtab #\J
(lambda (window)
(fill-circle window (cursor-position window) 12)))
(setf (comtab my-window) my-comtab)
(select-window my-window)))
(foo)Generic Function, cg package
Arguments: *window-or-widget line &optional relative-p
If relative-p is nil (the default), this function scrolls the window-or-widget so that line is the first visible line. If relative-p is true, scrolls the window so the first visible line is line lines from the current position.
window-or-widget may be a text-edit-window, text-edit-pane, multi-line-editable-text, single-item-list, multi-item-list, outline, or scrolling-static-text.
line should be an integer, identifying the line to be displayed (if relative-p is nil) or the number of lines from the current position to be displayed (if relative-p is true). Zero indicates the topmost line.
relative-p is a boolean which controls whether line should be interpreted as an absolute (value nil, the default) or a relative (value true) number.
The return value is undefined.
Generic Function, cg package
Arguments: window
This generic function is called whenever a window receives the keyboard focus. Applications may add :after methods in order to be notified when this occurs. The built-in methods should not be overridden. See also clear-focus.
An application may also call set-focus to move the keyboard focus to a particular window. This may not be particularly useful in most applications, because:
When programmatically moving the keyboard focus to a window, it is usually better to call select-window instead to ensure that the window also comes to the front.
set-focus-component can be called instead to move the focus to a particular widget, rather than calling set-focus on the window of the widget.
Common Graphics or the operating system normally moves the keyboard focus to an appropriate child window or control when a parent window is selected.
An application may also pass nil to set-focus to remove the keyboard focus from any window in the current thread, if any such window currently has the focus. This may be useful for momentarily disabling keyboard input, though with-events-disabled (which disables mouse events as well as keyboard input) may be preferable in most cases.
Generic Function, cg package
Arguments: grid-widget row-section column-section row column &optional (row-number 0) (column-number 0)
Changes which cell in grid-widget has the keyboard focus when the grid-widget itself has the keyboard focus. The focus is indicated by a rectangle that's drawn around the cell, unless the grid-widget's show-focus property has been turned off. grid-widget should be an instance of the grid-widget control/class.
An application can call this function to change the focus cell programmatically. Methods can also be added to catch whenever the focus cell changes, because this generic function is always called internally to change the focus cell when the user does so interactively, typically by pressing the arrow keys or clicking a cell. The built-in methods should not be overridden. An :around method avoids calling other methods if the specified cell is already the current focus cell.
The four remaining required and two optional arguments should be specified as follows:
row-section: the grid-row-section instance that contains the new focus-cell, and should be one of the row sections that are returned if row-sections is called on grid-widget. Row sections may alternately be found by calling functions such as row-section or next-section.
column-section: the grid-column-section instance that contains the new focus-cell, and should be one of the column sections that are returned if column-sections is called on grid-widget. Column sections may alternately be found by calling functions such as column-section or next-section.
row: the grid-row instance that contains the new focus-cell, and should be one of the rows that are returned if subsections is called on row-section. Rows may alternately be found by calling functions such as subsection or next-subsection.
column: the grid-column instance that contains the new focus-cell, and should be one of the columns that are returned if subsections is called on column-section. Columns may alternately be found by calling functions such as subsection or next-subsection.
row-number: the index of the particular replication of row that contains the new focus-cell, when row is a replicated grid-row (one whose section-count property is greater than one). The default is zero, indicating the first replication of the row.
column-number: the index of the particular replication of column that contains the new focus-cell, when column is a replicated grid-column (one whose section-count property is greater than one). The default is zero, indicating the first replication of the column.
To find the cell that currently has the focus within a grid-widget, call focus-cell.
See the description of the grid-widget control/class.
Generic Function, cg package
Arguments: widget-window &optional only-when-parent-has-focus
Moves the keyboard focus to the control or window. If only-when-parent-has-focus is true, then nothing is done if the focus is not currently in the parent of the control or window.
Generic Function, cg package
Arguments: dialog-item
This generic function is called when the keyboard focus moves to a control. Applications may add set-focus-event methods to handle this event for a whole subclass of controls as an alternative to writing individual on-set-focus event-handler functions for each control. Applications should not call set-focus-event.
The default method calls the on-set-focus event-handler function for the control specified by dialog-item, if it has one, and performs other internal functionality that should not be overridden.
See kill-focus-event.
Function, cg package
Arguments: window
The functionality described here is what happens when running in Windows desktop mode. When running in CG/JS mode, this function simply calls select-window on window.
This function makes the thread that created the specified window be the foreground thread, and selects the specified window. (The foreground thread is a Microsoft term and refers to the thread (typically an application) whose windows are currently in front, and one of which will have the keyboard focus.)
This function may be needed by multi-threaded Common Graphics applications because select-window or bring-window-to-front will not reliably move a window in front of windows that were created by other threads. We say "reliably" because these functions may do this in certain versions of Windows or in certain situations, but cannot be counted upon to do so.
Some versions of Windows allow only the current foreground thread or a thread created by the current foreground thread to set the foreground thread. In other cases, the taskbar icon corresponding to the specified window will be made to flash to notify the user that the window is asking to be brought to the foreground.
The function foreground-window returns the selected top-level window in Lisp only if Lisp is the currently-selected application.
See About using multiple threads in the IDE in cgide.html.
Generic Function, cg package
Arguments: stream graphics-context
Sets the various drawing style options of stream to the values that have been saved in graphics-context. stream should be a cg-stream.
The graphics-context passed in should have been returned by a call to copy-graphics-context, and graphics-context-p should return true for that stream and graphics-context (as it always will if the graphics-context were created from the same stream).
The graphics-context feature allows the various drawing styles such as line-width and font that are currently being used by a drawing stream to be saved into a single graphics-context object, and for that object to later be restored to that stream or another stream whenever that particular combination of drawing styles is desired once again. This can be more convenient than re-specifying each individual drawing style explicitly.
See copy-graphics-context (where all the information in a graphics-context object is described), make-graphics-context, graphics-context-p, and restoring-graphics-context.
Generic Function, cg package
Arguments: graphical-stream gradient-name
This is a convenience function on top of the *color-gradient-filling* facility, for using a particular hardcoded set of gradient settings rather than binding the four individual special variables. The only gradient-name that has been implemented is :rounded-top-and-bottom, which causes area-filling functions like fill-box to draw a convex rounded look that is lighter toward the top. This is used for nodes in Franz's Gruff graph database browser. Call clear-named-gradient to remove the effect, or use with-named-gradient to both set and clear the effect.
Typically you would use the macro with-named-gradient instead of this method, to ensure that the gradient status is cleared at the end.
This function works by setting the variables *color-gradient-filling*, *color-gradient-direction*, *color-gradient-intensity*, and *color-gradient-blend*.
stream is the Connon Graphics stream on which filling will be done using the gradient.
gradient-name is a keyword symbol that names one of the preset gradient styles. Currently :rounded-top-and-bottom is the only choice, which creates an effect similar to a raised button.
This facility was not designed for nested use, and exiting any with-named-gradient form will clear any gradient style.
This generic function is implemented only on Windows and JavaScript/HTML.
See also named-gradient.
Generic Function, cg package
Arguments: stream page-width page-height
Resets the page size of stream to the specified width and height. stream should be a cg-stream. This function may be more efficient than making separate calls to both (setf page-width) and (setf page-height).
For bitmap-pane's and bitmap-window's, the internal bitmap used to refresh the display is also modified to reflect the new dimensions when necessary. See page-width and page-height for more information.
Generic Function, cg package
Arguments: window &rest args
This function is specific to Windows desktop mode and should not be called in CG/JS mode.
Sets the paragraph format of window, which must be an instance of text-edit-pane. Note that a rich-edit-pane is an instance of text-edit-pane. Note further that neither a text-edit-window nor a rich-edit control are accepted as arguments. (A text-edit-window is usually the parent of a text-edit-pane. Applying window to a rich-edit control typically returns the rich-edit-pane suitable as an argument to this function.)
The other arguments set paragraph formatting characteristics. They are keyword arguments (and so should be specified in keyword/value pairs). They are as follows:
:justification: :justification should be is one of :left, :center, :right, or nil for no change.
:numbering-style: numbering-style is one of :bullets, :plain, or nil for no change.
:top-left-indentation, :body-left-indentation, :right-indentation, :top-left-indentation-is-relative: top-left-indentation, body-left-indentation, and right-indentation are each a number in points, or nil for no change.
top-left-indentation is the indentation of the first line of text. If top-left-indentation-is-relative is true, then top-left-indentation is relative to the current indentation of each affected paragraph.
body-left-indentation is the indentation of the second and following lines of text, relative to the first line of text.
right-indentation is the indentation of the right side of the text.
:tabs: tabs is a list of tab positions from left to right, specified in points, or t for no change. t is the default. nil would remove any tabs that are currently set. The Microsoft control allows up to 32 tab positions, and Common Graphics will simply ignore any beyond the first 32 in the list.
See cg-rich-text.html for information about rich text editing in Common Graphics.
function, cg package
Arguments: plot-widget &key value-index object-index object-id x y x-low x-high y-low y-high icon-size update-now &allow-other-keys
Establishes one or more of the values to display on a plot-widget for one of the points of one of the chart objects that are represented in a plot-widget. The return value is not defined.
An alternative to calling set-plot-value multiple times is to provide a plot-value-returner function that will be called as needed to return all of the plot's values. That approach is more efficient if you already have all of the plot's data stored somewhere such as in an array. The set-plot-value approach is somewhat more straightforward, and is more suitable if you are incrementally adding or modifying the data over time.
plot-widget is the widget to modify.
The first group of keyword arguments specify which value-index/object pair to modify.
value-index is the zero-based index of the plot value to modify, or the symbol :new to add a plot value to the existing values for the specified object, or the symbol :last to modify the most-recently-added plot value for the object (that is, the one with the highest index), or else nil to default to :new. If the plot is empty and value-index is :last, then it behaves like :new. To simply add new values, you can avoid passing this argument.
object-index is the zero-based index of the chart object to modify, or nil to not specify an object index. If both object-index and object-id are nil, then object-index defaults to zero. If both are true, then object-index takes precedence. If there is only one chart object, then there is probably no need to pass this argument or object-id.
object-id is the arbitrary ID of the chart object to modify, or nil to not specify an object ID. If object-index is nil and object-id is true, then if there is an existing object whose ID is object-id then it will be modified, and otherwise a new object will be created and its ID will be object-id.
(If there is no entry in the chart-objects property for the specified object-index or object-id, the chart-objects sequence is expanded to include such an entry.)
The next group of keyword arguments specify one or more values for the specified value-index/object pair. Any subset of these arguments may be passed, though the auxilliary values will have no effect until if and when the x and y values are both specified for the same value-index/object pair. An x, y, x-low, x-high, y-low, or y-high value may be either a real number to add a value to the plot or modify an existing value, or else nil to remove a value from the plot.
x is the X coordinate of a point to be plotted. This is always measured along a horizontal axis.
y is the Y coordinate of a point to be plotted. This is always measured along a vertical axis.
x-low is an additional value that is typically somewhat lower than the x value. It is drawn according to the high-low-value-style of the plot-view, and is typically used to represent an error range.
x-high is an additional value that is typically somewhat higher than the main value. It is drawn according to the high-low-value-style of the plot-view, and is typically used to represent an error range.
y-low and y-high are like x-low and x-high, except that they are plotted vertically from the main plotted point rather than horizontally from it.
icon-size is the size of the icon drawn at a particular plotted point. The value should be a positive integer to be used as the "radius" of the icon, measured in pixels, or else nil to defer to the icon-sizes of the icon-drawing-view. It is used only if the draw-icons property of the plot-view is true, and only if the icon-images property uses names of the built-in icons (which are :dot, :circle, :square, :triangle, and :diamond) rather than pixmaps. For :dot, the value refers to the diameter of the dot rather than the radius, to allow more accurate dot sizes.
update-now indicates whether to display the new value now. If nil, then the widget is invalidated so that it will be redrawn to reflect the new value, but as usual not until all queued events are handled. This allows adding many values quickly, which will then be displayed once at the end. If true, then the plot will be redrawn immediately. This allows animating the incremental adding of values. (If a sleep or mp:process-wait occurs between the adding of incremental values, then the widget should still redisplay at those times without passing this argument as true.)
Function, cg package
Arguments: pos x
Use of this function is deprecated. Use setf and position-x instead.
Sets the x component of the position pos to val.
Function, cg package
Arguments: pos y
Use of this function is deprecated. Use setf and position-y instead.
Sets the y component of the position pos to val.
Generic Function, cg package
Arguments: window x-max y-max &optional x-thumb-length y-thumb-length
This function should be called by an application only as part of a custom scrolling scheme that is implemented by overriding several default Common Graphics methods in order to scroll by logical picture objects rather than by pixels. This symbol is exported because it is one of the generic functions that need to be modified. See the example entitled "Scrolling by arbitrary objects rather than pixels" on the Examples tab of the Navigator dialog for a complete example and see the descriptions of horizontal-scroll-bar and vertical-scroll-bar.
When the default Common Graphics scrolling code (which always scrolls by pixels) is used, an application should set the page size of a window rather than calling this function to set the scroll-range. The page size may be set either by passing the :page-width and/or :page-height initargs to make-window or by calling set-page-size later. The page size is the size of the entire canvas that may be scrolled into the window. The scroll-range is the portion of the page size that does not fit into the window interior. So by setting the page size, the scroll-range is determined implicitly, including the "thumb" (scroll-box) lengths which correspond to the interior size of the window compared to the page size.
In releases prior to 6.0, setting the scroll-range of a window would automatically set its page size to match; this is no longer done. Applications should set the page size instead, as described above in this entry.
Generic Function, cg package
Arguments: stream start &optional (end start) &key (scroll t)*
Sets the selected text in stream, which must be a text-edit-pane or a text control (such as an editable-text or multi-line-editable-text), to be the characters indexed by start (inclusive) and end (exclusive). If start equals end, the cursor is placed before the character at start, but no text is selected. Indexing is zero-based so the first character is index 0. The end of the buffer may be specified by passing start or end as a very large integer such as the value of most-positive-fixnum. If end is nil or unspecified, it will default to start.
If scroll is true, as it is by default, and the newly selected text (or text cursor position) is not currently scrolled into view, then it will be scrolled into view automatically. If you wish to specify scroll as nil, you must provide a value for end. nil is a suitable value if you do not otherwise intend to specify one.
Since a text-edit-pane is a stream, the function file-position may alternately be used to return or set its text cursor position, and file-length will return the index of the end of the buffer. (Calling window on a multi-line-editable-text widget will return its associated text-edit-pane.)
This function also works on editor buffers (instances of lisp-edit-pane). For a simple test of this function, open an editor window (click View | New Editor. Click on Tools | Get Component and click on the editor pane. The object will be returned in the Debug Window. In the Debug Window, evaluate
(setq lp *)Now, in the editor pane, enter
0123456789
0123456789(with no spaces).
(set-selection lp 0 2) selects 01 in the first line.
(set-selection lp 0 10) selects all characters in the first line.
(set-selection lp 0 13) selects all the first line and 0 in the second line. (the 11th and 12th characters are the carriage-return and linefeed).
See also get-selection.
Function, cg package
Arguments: simple-stream indicator value
This function is intended for use in device and location managers and may only be applied to simple streams. It sets user-definable stream properties that are stored on the stream plist.
Generic Function, cg package
Arguments: tab-control &key (width (default-tab-width (configuration *system*))) (height (default-tab-height (configuration *system*)))
Sets the pixel height for each row of tabs on tab-control, and sets the width for a fixed-width tab-control. May be more efficient than changing the width and height individually.
Generic Function, cg package
Arguments: text-edit-pane string
Sets the contents of a text-edit-pane to be string. For line breaks, the string may contain either single #\Newline or #\Linefeed characters, or #\Return #\Linefeed (CR/LF) pairs.
The other way to replace all of the text in a text-edit-pane (assuming that it is not associated with a multi-line-editable-text control) is to call clear-page on the pane and then write text to it with standard Common Lisp stream output functions (like format).
Note: set-text would actually work when called on certain other objects, but is too low-level for application use for all but text-edit-pane. Specifically, set-text would also set the contents of a multi-line-editable-text control, but (setf value) should be used instead so that the control's current value will reflect the current string. Similarly, set-text would set the title of a frame-window (as well as other things), but (setf title) should be used instead so that the window will remember the title.
See also get-text, which returns (as a string) the text in a text-edit-pane and in text controls.
Generic Function, cg package
Arguments: text-edit-pane zoom-ratio
This generic function is implemented only on Windows.
Sets the current zoom ratio of a text-edit-pane or rich-edit-pane. The value should be a rational number (an integer or ratio) between 1/64 and 64, inclusive. The size of the text will then be multiplied by this amount.
The zoom ratio may revert to 1 when doing things like replacing the text with set-text or (setf rich-edit-range). If you don't know the current zoom ratio (perhaps because something like a special mouse wheel driver has changed it) and you want to preserve the current zoom ratio, then you could do that with code similar to this:
(let* ((zoom (get-text-zoom my-text-edit-pane)))
(set-text my-text-edit-pane "new text ...")
(set-text-zoom my-text-edit-pane zoom))See also get-text-zoom.
Generic Function, cg package
Arguments: list-view
This function returns a boolean value indicating whether the image-lists used by a list-view control will remain open when the list-view's pane is closed by either removing the list-view from its dialog or by closing the dialog. If nil, then any image-lists that were the value of the small-image-list, large-image-list, and state-image-list properties of the list-view will be closed when the list-view's pane is closed. If t (the default), then the image-lists will not be closed.
Since Common Graphics automatically opens a closed image-list when it is assigned to a list-view control, the desirable value of this property is basically a matter of efficiency. If an image-list is shared by multiple list-views that are created and destroyed at different times, then it is probably best to leave this property turned on in list-views that use the shared image-list to avoid the needless closing and re-opening of the image list. But if each list-view uses its own image-list, it may be desirable to turn this property off so that the memory or Windows resources consumed by the image lists of a list-view is automatically freed up when the list-view window is closed.
See list-view.
Generic Function, cg package
Arguments: outline outline-item-or-value direction
Shifts an outline-item on an outline widget (specified by the outline argument) either vertically or horizontally relative to its neighboring items. Shifting vertically will change the position of the item among its sibling items, exchanging it with the item that's just above or below it. Shifting horizontally will change the indentation of the item (when possible), which puts the item under a different parent item.
outline-item-or-value may be either an outline-item, the value of an outline-item, or nil. When non-nil, the specified item is shifted. When nil, the currently selected item is shifted, and if multiple items are selected (see multiple-selections) then all of them will be shifted. Nothing is done when this argument is nil and there are no selected items, or when the operation cannot be done (such as when attempting to shift an item rightward when it is the first item under its parent item).
The direction argument may be one of the keywords :down, :up, :right, or :left.
See also outline-items-reordered, outline-item-added, and outline-item-removed.
Generic Function, cg package
Arguments: window menu
Returns a list of menu-items to be shown in a pop-up-menu whenever pop-up-shortcut-menu is called on window.
The default mouse-right-down methods for basic-pane and dialog-item call pop-up-shortcut-menu on the window that was clicked. Therefore, a menu of shortcut commands can be implemented for a window or dialog-item subclass simply by writing a shortcut-commands method that specializes on the class. This may be more convenient than the general menu approach of calling open-menu and pop-up-menu. (And this behavior may be overridden by adding a more specific primary mouse-right-down method.)
The default method returns nil, which causes pop-up-shortcut-menu to do nothing.
Generally, the value of each menu-item in the returned list should be a function name, and this function is called with window as the only argument when the user chooses that menu-item. Alternately, the menu-item value may be a window, in which case the window is selected by calling select-window on it. This default behavior may be changed, however, by writing custom shortcut-menu-class methods; see pop-up-shortcut-menu and shortcut-menu-class for details.
window is the window that was passed to pop-up-shortcut-menu, which will be the window that was clicked when called from the default mouse-right-down methods.
menu is the menu to which the returned menu-items will be added. This argument is probably only useful if you customize the on-click behavior by subclassing shortcut-menu and writing shortcut-menu-class methods; you could then specialize on your shortcut-menu subclass here. In the usual case, the argument is ignored (as in the examples below).
Window example:
(defclass my-window (frame-window)())
(defmethod shortcut-commands ((window my-window) menu)
(declare (ignore menu))
(list (make-instance 'menu-item
:title "Beep"
:value 'beep)
(make-instance 'menu-item
:title "Move Down"
:value #'(lambda (window)
(move-window-relative
window #.(make-position 0 16))))))
(make-window :foo :class 'my-window
:width 300 :height 200
:title "Right-Click Me!")** Widget example**
In the example below, the functions that are the values of the returned menu-items will be passed the window of the dialog-item, rather than the dialog-item itself. This requires subclassing both the dialog-item (in the example, a single-item-list) class and the associated widget-window subclass (in the example, a single-item-list-pane), linking them with a widget-device method, and then specializing a shortcut-commands method on the new my-item-list-pane class.
(defclass my-item-list (single-item-list)())
(defclass my-item-list-pane (single-item-list-pane)())
(defmethod widget-device ((dialog-item my-item-list)
(dialog dialog))
'my-item-list-pane)
(defmethod shortcut-commands ((window my-item-list-pane) menu)
(declare (ignore menu))
(list (make-instance 'menu-item
:title "Beep"
:value 'beep)
(make-instance 'menu-item
:title "Change Color"
:value #'(lambda (window)
(setf (background-color
(dialog-item window))
(make-rgb :red (+ 128 (random 128))
:green (+ 128 (random 128))
:blue (+ 128 (random 128))))))))
(make-window :bar :class 'dialog
:title "Right-Click the Widget!"
:width 300 :height 200
:dialog-items (list (make-instance 'my-item-list
:range '(one two three)
:left 30 :top 20
:value 'one)))Generic Function, cg package
Arguments: window
Returns the class of the shortcut (right button) menus in window.
Function, cg package
Arguments: window
Enables the caret of window if it has been disabled with hide-caret and currently has the keyboard focus.
Generic Function, cg package
Arguments: list-view
This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.
Returns the value of the show-check-boxes property of a list-view control. The value may be set at creation time by passing the :show-check-boxes initarg to make-instance, or any time later by calling (setf show-check-boxes).
This property specifies whether a list-view has a special column of check boxes on the left side of the control. When the user clicks a check box in this column to toggle its state, the (setf checked) generic function will be called, which will call the list-view-item's on-check function if it has one. An application may also call (setf checked) programmatically to change the state of the check boxes.
The value can be nil or true. The default is nil.
show-check-boxes should not be used along with a state-image-list, because it is implemented as a special type of state image list.
Function, cg package
Arguments:
This function exists only on the Windows platform. On Linux and the Mac, Allegro CL and the IDE are typically started from a shell window or an Emacs buffer and that window/buffer serves the function that the console does on Windows.
Shows the Allegro console window if it exists and is currently hidden or iconized, and otherwise does nothing. See also hide-console.
(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)
Generic Function, cg package
Arguments: grid-widget
Returns (or sets with setf) whether grid-widget, when it has the keyboard focus, will draw a rectangle around the cell that has the keyboard focus to show that that cell has the focus. The default is t, but it may be desirable to turn this property off if a grid-widget is being used for display only rather than for keyboard input, or if no cell-specific keyboard event-handling code is supplied for a grid-widget.
show-focus is a property of the grid-widget class.
Generic Function, cg package
Arguments: calendar-widget
A boolean value indicating whether a rectangle is drawn around a calendar widget whenever it has the keyboard focus.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: list-view
This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.
Returns the value of the show-grid-lines property of a list-view control. The value may be set at creation time by passing the :show-grid-lines initarg to make-instance, or any time later by calling (setf show-grid-lines).
This property specifies whether a list-view will draw subtle grid lines between its rows and columns. This can help the user tell which strings in different columns are on the same line when there may be large gaps between the columns. The value can be nil or true. The default is nil.
Generic Function, cg package
Arguments: object
Returns whether the help-string of a window, widget, or hotspot is automatically displayed in an available status bar (if any) when the mouse cursor moves over the object. The value may be set at creation time by passing the show-help-string-under-mouse initarg, or any time later by calling (setf show-help-string-under-mouse). The default value is nil.
When nil, this property has no effect.
When true, then whenever the mouse cursor is moved over the object, the object's help-string is displayed in a status bar if a suitable common-status-bar or status-bar is found. When the mouse cursor moves off of the object, a blank status bar message is displayed to erase the help string.
A status bar is found by first looking for one on the window itself when object is a window, or else by looking on the parent window of the widget or hotspot. If that window does not have a status bar, then successive ancestor windows are checked until a status bar is found. If no status bar is found, then nothing is done.
This behavior is implemented with mouse-in and mouse-out methods that call window-message.
This property is not implemented on html-widget, where it does not appear feasible.
Generic Function, cg package
Arguments: pull-down-menu
This property of menus returns whether the help-string of any menu-item on pull-down-menu will be presented as a tooltip just below the menu if the user holds the mouse cursor over the menu-item for menu-tooltip-delay milliseconds. (When the help-string property of the menu-item is nil, no tooltip is shown even when this property is turned on.)
The default value is nil, and the value may be changed at any time by calling the setf of this function. When this property is not used, an alternative way to display menu-item help-strings (though with no delay) is to write a menu-item-highlighted method that displays the help-strings in some custom way.
This property is implemented only for menus that pull down from menu-bars and for their child menus, and will have no effect on pop-up-menus.
There is a control on the Menu Editor dialog for toggling this property individually for any menu in the menu hierarchy that is being edited in the dialog.
Generic Function, cg package
Arguments: outline &key all-descendents
Causes the child items of the currently selected outline-item to be displayed. This is similar to open-outline-item-value except that it works on the currently selected item rather than on the item that has a specified value, and it has the all-descendents option.
If all-descendents is true, then all descdendent items will be shown rather than the immediate children only.
This function could be called directly for an interactive command to open the selected item.
Function, cg package
Arguments:
CG calls this function to determine which way to show parenthesis-matching marks. In CG/JS mode this always returns true (because the alternative is not implementable), and elsewhere it returns the value of *show-parenthesis-matches-as-pop-up-window*, which an application could modify. There's probably no reason for an application to call this function, except maybe to find out which style is being used.
Generic Function, cg package
Arguments: component
This property indicates whether the selected value in a component will be highlighted even when the component does not have the keyboard focus. component may be either a text-edit-pane or rich-edit-pane window, or a list-view, editable-text, lisp-text, multi-line-editable-text, or multi-line-lisp-text control.
If nil, then the selected value is highlighted only when the component has the keyboard focus. The advantage with this choice is that the highlighting does not distract from the component that does have the keyboard focus. It may also clarify which component has the keyboard focus, though officially the focus is indicated in some other way, such as with a dashed rectangle.
If true, then the selected value will always be highlighted. The advantage with this choice is that the user can always see what the selected value is if they might need to do so even when the component does not have the focus.
This property may not be modified after the component has been created. The value must be specified at creation time either by passing the show-selection-when-unfocused initarg to make-instance (for a dialog-item) or make-window (for a window), or by specifying the value in the inspector when designing a form interactively.
Generic Function, cg package
Arguments: widget
This generic function is called internally to show the tooltip of a control. This function is not normally called by an application, but wrapper methods may be added to act when a tooltip is invoked after the mouse pauses over a control. This may be useful, for example, for displaying some other form of help (such as a status-bar message) after the mouse has paused over a control.
Note that this generic function is called even if the show-tooltips configuration option has been turned off. This allows showing some custom form of help for a control without using tooltips, which may be handy if tooltips are considered more annoying than a status-bar message, for example.
See also hide-tooltip and tooltip-delay.
Here is an example method that could be added to cause dialog-item help-strings to be displayed in the status-bars of their parent windows (or other ancestor windows) whenever the mouse cursor pauses over any dialog-item. See help-string.
(defmethod show-tooltip :after ((widget dialog-item))
(let* ((help-string (help-string widget)))
(when help-string
(window-message (parent widget) "~a" help-string))))Function, cg package
Arguments: window string-list tooltip-horizontal-center tooltip-top &key (justification :center)(font (tooltip-font)) allow-over-status-bars
Shows a tooltip at an arbitrary time and place. This is a lower-level function than the tooltip facility for widgets and hotspots, where you simply assign a tooltip string to a widget, and then CG takes care of showing it in a standard place below the widget after a delay when the mouse cursor is moved over the widget.
This function simply displays a tooltip window at some arbitrary place when you call the function. You need to decide if and when to call this function, and where to place the tooltip window, and then you need to call hide-tooltip when you want the tooltip to go away. CG sizes the tooltip window for you so that the text fits within it.
window is the window over which the tooltip will be displayed.
string-list is a list of strings, where each string will appear as one line of text in the tooltip window. You could call split-string-to-width to convert a string into the multiple lines of text.
tooltip-horizontal-center is the x coordinate of the horizontal middle of the tooltip window in the stream coordinates of window. Typically you would specify this as the horizontal middle of a thing that's drawn in the window, which the tooltip is describing, to align the tooltip window horizontally with whatever it is describing
tooltip-top is the y coordinate of the top of the tooltip window in the stream coordinates of window. Typically you would specify this as a coordinate that's a little below the bottom of a thing that's drawn in the window, which the tooltip is describing, to place the tooltip just below whatever it is describing.
justification is how the lines of text are horizontally aligned with each other in the tooltip window, and can be either :left, :center, or :right. This has no effect when there is only one line of text.
font is the font in which the text will be printed in the tooltip window.
allow-over-status-bars determines whether to avoid placing the tooltip over a status bar, where it may obscure the text in the status bar. When true, the tooltip will be placed at the specified coordinates as usual. When nil, the tooltip will be scooted away from that position to avoid obscuring the status bar.
Generic Function, cg package
Arguments: configuration
Returns the value of the show-tooltips property of configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
If the value of the property is true, tooltips (small windows with brief messages) will be displayed when the mouse cursor moves over an object with a tooltip. A common use of tooltips is to display the name of an object represented on the screen by an icon. show-tooltips is a property of the configuration class.
A tooltip may be given to a widget (dialog-item), a hotspot, or a button-info of a multi-picture-button widget. A tooltip can be set either by passing it as the value of a tooltip initarg to make-instance, or by calling (setf tooltip) later.
You can examine and change configuration options with the inspector. Choose Tools | Inspect System Data | Configuration Options.
Function, cg package
Arguments: window state
This function should not be called by user/programmer code. It occasionally appears in code automatically generated in earlier releases and that code should still work.
Function, cg package
Arguments: window hide-p
If hide-p is true, window is completely hidden from view, after which its state will be :shrunk. Otherwise, window is shrunk to an icon, after which its state will be :icon.
Generic Function, cg package
Arguments: standard-object
Returns a list of siblings of the argument. Siblings are the fellow children of a control's or a window's parent and the list contains the argument as well. This list is set by the system and cannot be set directly by a program.
Because each object is its own sibling, the value is never nil.
Generic Function, cg package
Arguments: multi-item-list-or-outline
Returns whether multi-item-list or outline control requires the user to hold down the Control key while clicking an item in order to toggle the selected state of that single item. If nil, a simple left click will deselect all other items (which is typical Windows behavior); if true, a simple left click will toggle the clicked item only. Note that holding down the Shift key while clicking to select a whole range of values (also typical Windows behavior) is possible only when this property is nil. The default value is nil for multi-item-list and t for outline.
For a multi-item-list, this property must be specified with the :simple-click-toggle initarg to make-instance when creating the multi-item-list instance; it cannot be changed later. For an outline, this property is used only when the multiple-selections property is true.
simple-click-toggle is a property of the multi-item-list and outline classes.
Generic Function, cg package
Arguments: common-status-bar
Returns (or sets with setf) whether common-status-bar is in simple mode. In simple mode, a common-status-bar is not sectioned, but remembers the positioning and text contents of its various sections (officially called parts), which will once again be displayed if the common-status-bar is returned to non-simple mode.
Note that calling status-bar-message also switches the simple-mode according to the :part keyword argument, whose default is zero. If the part argument is :simple, then simple-mode is turned on and the message is written across the entire status-bar (as needed). Otherwise the sections are shown and the message is displayed in the requested part. So (setf simple-mode) is used only for switching between displaying the sectioned messages and displaying the unsectioned message after both sets of messages have been written to the status-bar with status-bar-message.
Generic Function, cg package
Arguments: tab-control
Returns the value of the single-line property of the argument. This property determines whether tabs on the tab-control widget will display in a single unbroken line or whether they wrap into several rows to display all at once in the window.
This option is specific to Windows desktop mode. In CG/JS mode a tab-control is always in single-line mode.
The single-line property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :single-line initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
The possible values and their effects are:
nil: tabs are arranged into as many rows deep as needed to fit all of the tabs at once along the uppermost portion of the control. All tabs are visible all the time.
t: tabs all appear in a single line across the tab-control control's top edge. A horizontal scroll bar appears at the right corner when there is not enough room to show all tabs in a single line.
single-line is a property of the tab-control class.
Generic Function, cg package
Arguments: grid-widget section subsection
Invoked when the user clicks inside a cell and moves the mouse at least *start-drag-slack* pixels while the mouse is down, to allow dragging the cell's row or column to a new position. The cell's row or column should be of class row-sizing-column-mixin or column-sizing-row-mixin for the click to invoke this method. See grid-widget.
Function, cg package
Arguments: window-or-widget
This property has an effect only in CG/JS mode. It should always be specified by passing a :small-canvas-mode initarg to make-window or to make-instance for a widget, though the function could be called later to see whether a window is in this mode.
When nil (the default), drawing in the window works in the standard JavaScript way where the window has a JavaScript canvas that's as large as the whole scrolling page (see page-width and page-height). The JS canvas remembers everything that has been drawn that can be scrolled into view. And if you have added a draws-the-entire-scrolling-page method that returns true, then scrolling the window does not require anything to be redrawn, which is the complete Javascript convention.
When true, the JavaScript canvas will be only as large as the interior of the window. This still avoids redrawing the window when it gets uncovered, but scrolling will always redraw the content that gets scrolled into window. (For efficiency, you should not supply a draws-the-entire-scrolling-page method that returns true for a window that's in small canvas mode.)
Small canvas mode is needed if the page-width or page-height of the window is greater than 32767, because the browser will not make a JavaScript canvas that large because of the memory that it requires to save the value of every pixel. CG will automatically switch a window into small canvas mode whenever a page-width or page-height greater than 32,000 is requested, so an application doesn't need to handle that itself. But you may want to use small canvas mode even at smaller page sizes to reduce memory consumption and the time that it takes to swap in fairly large JavaScript canvases.
Small canvas mode is the way that CG always works in Windows desktop mode, where it is the natural mode. It may be that the only big advantage with NOT using small canvas mode is when using it along with draws-the-entire-scrolling-page for extra fast scrolling, because then nothing is redrawn while scrolling. Yet small canvas mode is off by default in order to use the usual JavaScript convention.
In the default mode where neither small canvas mode nor draws-the-entire-scrolling-page is used, scrolling content into view for the first time will leave the area that's newly scrolled into view momentarily blank until your application draws the newly-visible content for the first time. So you may want to use one of these two optional modes to avoid a flashing effect.
For use with a widget (dialog-item) rather than a custom application window, small canvas mode may be useful only with a few kinds of widgets that might have large scrolling pages. And it is not useful for widgets of type os-widget (including item-list and list-view) because they are assembled from HTML elements and do not use a JavaScript canvas at all. So its usefulness would be limited to widgets of type lisp-widget. And while the grid-widget and the chart-widget do scrolling, they use special techniques where this mode would not come into play. That leaves the outline and scrolling-static-text widgets as the only ones where small canvas mode is likely to be useful. The main outline in the IDE's trace dialog uses small canvas mode, and therefore can collect many thousands of traced calls.
A :no-canvas-mode initarg can alternately be passed as true to make-window when drawing is never done on that window. That will save memory by not creating a JavaScript canvas for the window at all. The window will still display its background-color.
Generic Function, cg package
Arguments: list-view
An image-list instance that contains the pixmaps to display in this list-view when its layout-style is either :small-icon, :list, or :report. May also be nil (the default) to display no icons in these layout styles.
As a shortcut, this property may alternately be specified as a list of pixmap names such as would be passed as the :pixmap-names initarg when calling make-instance on the image-list class. This requires that the pixmaps have been cached already, such as by calling load-pixmap followed by cache-pixmap. In this case, an image-list instance will be created with the specified pixmaps, and that image-list will then be the value of this property. This is handy when specifying an image-list interactively in the inspector while building a form for a dialog. On the other hand, specifying an actual image-list programmatically allows for a single image-list to be shared among multiple list-view controls to save memory or Windows resources.
A small-image-list typically contains pixmaps that are 16 by 16 pixels in size. They can be other sizes, but may get clipped if larger due to the limited space that is reserved for the icons.
The icons will appear only if one or more of the list-view-items of the list-view have non-nil values for their icon-index property.
Here are three alternative ways of specifying the cached pixmaps named :default-opened and :default-closed as the small icons of a list-view control:
(setf (small-image-list my-list-view)
(make-instance 'image-list
:pixmaps (list (find-pixmap :default-opened)
(find-pixmap :default-closed))))
(small-image-list my-list-view) ==> #<image-list :image-list-1 ...>
(setf (small-image-list my-list-view)
(make-instance 'image-list
:pixmap-names '(:default-opened :default-closed)))
(small-image-list my-list-view) ==> #<image-list :image-list-2 ...>
(setf (small-image-list my-list-view)
'(:default-opened :default-closed))
(small-image-list my-list-view) ==> #<image-list :image-list-3 ...>See list-view.
Function, cg package
Arguments: fontmetrics ascent descent leading external-leading internal-leading height fixed-width-p truetype-p vector-p device-p average-char-width max-char-width direction
Modifies the fontmetrics object specified by the fontmetrics to have specified values. For use in nfontmetrics methods.
See also Text and Fonts in cg-drawing.html.
Generic Function, cg package
Arguments: object
When object is a grid-widget, returns the grid-column by which grid-widget will be sorted whenever sort-grid is called on it. The current sort-column can be changed by calling (setf sort-column) with either the grid-column or its name. setf'ing the property does not sort the grid column.
When object is a list-view, returns the name of the list-view-column by which the list-view is currently sorted. Setf'ing this property sorts the list-view by that column.
An application could call (setf sort-column) and sort-grid directly to sort a grid-widget at any time, perhaps in a custom cell-click method, or it could use the built-in interactive interface provided by the row-section-with-sort-gadget-mixin class, which provides its own cell-click methods that call these functions internally.
sort-column is a property of the grid-widget and list-view classes.
Generic Function, cg package
Arguments: grid-widget
Sorts the rows in the focused row-section of grid-widget by the current sort-column of the grid and that column's on-sort-predicate.
An application could call (setf sort-column) and sort-grid directly to sort a grid-widget at any time, perhaps in a custom cell-click method, or it could use the built-in interactive interface provided by the row-section-with-sort-gadget-mixin class, which provides its own cell-click methods that call these functions internally.
If reading cell values takes significant time, sorting a grid could be sped up by turning on the cache-cell-values property of the grid-widget.
Generic Function, cg package
Arguments: row-section-with-sort-gadget-mixin
This boolean property determines how an instance of the row-section-with-sort-gadget-mixin class (in a grid-widget) implements mouse clicks as a default interactive interface to sort-grid, sort-column, and sort-reverse. The initial value is t, which invokes the simpler and more intuitive style. A value of nil implements another style largely for backward compatibility. setf may be used with this function to change the value. See row-section-with-sort-gadget-mixin for details.
Generic Function, cg package
Arguments: grid-widget
When object is a list-view, returns or sets with setf the value of the sort-reverse property of the argument. This property is a boolean (only meaningful values are nil and true) which specifies the sort order of the control. The sorting will reverse if the value of this variable is switched.
When object is a grid-widget, returns (or sets with setf) whether it will be sorted in the reverse order of the order specified by its current sort-column's on-sort-predicate whenever sort-grid is called on it.
sort-reverse is a property of the grid-widget and list-view classes.
Generic Function, cg package
Arguments: grid-column
When using the row-section-with-sort-gadget-mixin class to provide the default interactive interface to the sort-grid function, the sortable property of a grid-column indicates whether the end user may set this grid-column as the current sort-column of the grid-widget by clicking on it in the grid cell at the intersection of the column and the mixin's grid-row-section. If this property is true, then the appropriate mouse click (according to the grid-widget's sort-on-click property) will set the sort-column; if nil, then nothing will happen.
The property value may be set by calling (setf sortable) or by passing the :sortable initarg when calling make-instance to create a grid-column. The default value is true.
Generic Function, cg package
Arguments: pixmap
Returns (or sets with setf) the path namestring of the .bmp pixmap file from which this pixmap's image was originally read (if any). This property will be nil if the pixmap was created by specifying the pixels and colors and so on programmatically rather than by loading the pixmap from a .bmp pixmap file with load-pixmap. source is a property of the pixmap class.
Function, cg package
Arguments: graphical-stream
Returns the pixel width of a space character in the current font of a graphical-stream. If the font is a fixed-width font, then this is of course the width of any character printed to the stream.
The value returned by page-width, left-margin, or right-margin is measured in space widths when the stream-units-p argument is nil.
Generic Function, cg package
Arguments: multi-picture-button
Returns the value of the spacing property of the argument. spacing is a non-negative integer indicating the number of pixels of extra space to place around the outside of each button-info's borders (the buttons of a multi-picture-button control are instances of the button-info class).
spacing is a property of the multi-picture-button class.
Generic Function, cg package
Arguments: line-graph-view
Returns the value of the span-missing-items property of a line-graph-view. The value may be set at creation time by passing the span-missing-items initarg, or any time later by calling (setf span-missing-items).
A boolean value indicating whether line segments will be drawn across chart items that have no values in a line-graph-view of a chart-widget. The default value is nil.
The chart-widget allows any combination of a chart item and chart object to either have a value or not. When there is no value, nothing is drawn on the chart for that chart item and object.
A special case is that a chart object may have no value for a sequence of one or more chart items, but have values for items on both sides of that sequence of items. This raises the question as to whether a line should be drawn between the groups of items that do have values.
If span-missing-items is true, then a single straight line is drawn between the last chart item before the sequence of non-value items and the first item after the no-value items. If span-missing-items is nil, then no such line is drawn, and lines will connect only contiguous items that all have values.
This property is used only when the draw-lines property is true.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: printer
Returns an integer indicating the version of the Windows printer information facility that is supported by the printer driver of printer. Specifically, if the value is #x400 or greater, then that printer driver knows how to give information on several new printer attributes that were added to the Windows printer information facility in Win95 and NT 4.0. If the number is lower than #x400, than some of the properties of printer may be nil because the printer driver did not know how to supply the newer values to the operating system.
spec-version is a property of the printer class.
This function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Function, cg package
Arguments: string width stream &key delimiters (split-only-at-newlines-when-present t)
Separates a string into lines of text that will fit into a specified pixel width. Returns a list of substrings of the specified string, splitting the string where any of the specified delimiter characters occur beyond the specified pixel width. The individual lines of text could then be drawn onto a stream within that pixel width.
Each element in the returned list is a list of (1) the substring for one line, (2) the pixel width of that substring, (3) the starting index of the substring within the original string, and (4) the ending index.
When #\space is a delimiter it will be removed, but other delimiter characters will be retained. This is to emulate the way the underlying windowing system wraps text in the CG function draw-string-in-box, but using this function instead allows the app to know where the wrapping is done.
string is the Lisp string to split.
width is the width in pixels into which the string will be wrapped.
stream is the stream onto which the string will be drawn, in case the underlying windowing system uses a different pixel width for text in different kinds of graphical streams, even when using the same font.
delimiters is a list of characters at which the string can be split. When unspecified or nil, it will default to *text-wrapping-delimiters* if *wrap-text-in-cg* is true, and otherwise it will default to a list of only the space character.
split-only-at-newlines-when-present, when true, will cause the string to be split only at newline characters when there are in fact one or more newline characters in the string.
function, cg package
Arguments: thing
This function is the initial value of the data-read-converter property of every grid-column of a spreadsheet widget (when it is created interactively by placing it onto a form window). It truncates floating-point values to two decimal places, to avoid requiring wide grid columns. Below is the code for this function, in case you'd like to substitute a similar custom function, such as one that truncates floats differently. This function is an example of how a data-read-converter function converts data that the grid-widget reads from somewhere into the strings that it displays in grid cells.
(defun spreadsheet-value-printer (thing)
(typecase thing
;; When the value is nil, show a blank cell rather than "nil".
(null "")
;; Print floating-point numbers to two decimal places,
;; to fit in narrower cells.
(float (string-trim '(#\space)(format nil "~32,2f" thing)))
;; Print other values in the default way.
(t (princ-to-string thing))))Generic Function, cg package
Arguments: app
The form (standalone-application (app *system*)) returns true if the Lisp that is running is a standalone application that was generated from an IDE project using the File | Build Project Executable menu command or the File | Build Project Distribution menu command. Otherwise nil is returned.
If you instead generate a standalone Common Graphics app with a direct call to generate-application, then you could set this yourself if desired in the startup code of the application by calling (setf standalone-application). This should be done after calling initialize-cg but before calling event-loop.
The value is used internally to determine what happens when an error is signaled and is not handled by application code. If set to :debuggable, then event-loop will use an error handler that shows a break in the console window; this will be the value in a standalone application that was generated with :allow-runtime-debug in the build-flags of the project (reflected by the "Enable Debugging of Runtime Errors" check-box on the Project Manager Build tab). For any other non-nil value, event-loop will use an error handler that displays a basic end-user dialog about an unhandled error and then exits. When nil, then no error handler is added by event-loop; this is the case in the IDE, where the IDE's own error handler will show the Restarts Dialog.
An application could use this value to behave differently when it is being run as a standalone application than when it is run as a project in the IDE.
Function, cg package
Arguments:
Starts a CG/JS client to show the running CG app in the default web browser on the machine where the CG application is running. It does this by telling the default web browser on the same machine to visit a URL like localhost:12345 (if the CG app's "Browser Server Port" option is 12345), just as if a user interactively entered that URL into the browser's URL widget.
Typically there is no need to call this function, because it is called automatically whenever running a standalone application in CG/JS mode, as long as the application was generated from a project in the IDE and the project's "Start Local Client" option is enabled. It is also called when running a project in CG/JS mode while the IDE is running in Windows desktop mode, and when running the IDE itself in CG/JS mode. But it could be needed when loading CG into a base Lisp or when generating a CG app from scratch without using the project system.
Function, cg package
Arguments:
Starts the CG/JS server. Typically there is no need to call this function, because it is called automatically whenever running a standalone application in CG/JS mode, as long as the application was generated from a project in the IDE. It is also called when running a project in CG/JS mode while the IDE is running in Windows desktop mode, and when running the IDE itself in CG/JS mode. But it could be needed when loading CG into a base Lisp or when generating a CG app from scratch without using the project system. It needs to be called once in any Lisp before doing any other CG/JS activity other than calling initialize-cg.
Here is a typical sequence of forms to evaluate to load CG into a base Lisp and then start up CG/JS and run a CG function. The :app-function would normally be something much more significant than this trivial example.
(require :cg)
:pa cg-user
(setf (cgjs-server-option :run-as-web-browser-server) t)
(defun my-app-function ()
(make-window :foo :class 'text-edit-window))
(setf (cgjs-server-option :app-function) 'my-app-function)
(initialize-cg)
(start-cgjs-server)
(start-cgjs-client)If you modify my-app-function, you can test the updated version by just closing the previous browser tab and calling start-cgjs-client again.
Generic Function, cg package
Arguments: printer
Returns the first page of the range of pages to be printed by printer, as requested by the user on the print job dialog. The application should interpret the start-page and end-page properties of the printer stream and print only the appropriate part of the output.
start-page is a property of the printer class.
This function is not setf'able. You must specify a value for this property when a printer stream is created with open-stream using the :start-page initarg. (It can also be changed in the printer job control dialog when printing is initiated by a user, but the initial value in the job control dialog cannot be changed.)
Generic Function, cg package
Arguments: grid-widget
If the edit-start-trigger of the focus-cell of the grid-widget is :get-focus, then this is whether text editing will begin automatically when the grid-widget itself gets the keyboard focus, rather than only when the focus shifts within the grid-widget to the cell.
Generic Function, cg package
Arguments: timer &key interval
Starts timer, which must be an instance of the timer class, running. If interval is true, then the timer's interval property is first set to this value. An interval should be a positive integer indicating the number of milliseconds between successive firings of the timer.
If the timer is already active, it is stopped and then immediately restarted using its current interval. This differs from setting the active property to true, which starts the timer only if it is not already active.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: widget
state works differently on outline-items, as described below under the heading State on outline-items.
This generic function returns two values. The first is the state of the argument, which should be a window or a visible control of some sort. Possible values for most objects are :normal and :shrunk. Windows can also be :icon, and :maximized. The second returned value is described under the heading Second returned value below.
:normal: the control or window has its normal size and is visible.
:shrunk: the control or window is shrunken and not visible.
:icon: the window is shrunk to a visible icon.
:maximized: the window is extended to its maximum size.
The associated generic function (setf state) is called whenever the state of a window is changed, either programmatically by calling other exported functions such as shrink-window, expand-window, and zoom-window, or interactively when the user clicks the shrink, maximize, or restore buttons on a window frame.
The value argument to (setf state) can be passed as :expanded to expand the window to :normal or :maximized, whichever it was before being shrunk (if it has never been expanded, it is made :normal). Note that :expanded is not a true state, so the resulting state of the window will be either :normal or :maximized.
A (setf state) :around method prevents any other non-:around :expanded state to either :normal or :maximized and passes that value to the other (setf state) methods that it calls, so any primary, :before, or :after :expanded state.
The generic functions state and (setf state) may be called on dialog-items or windows, while the other three functions apply only to windows.
state returns a second value for the "expanded state" of the window. This value is always either :normal or :maximized. If the current state of the window is :shrunk or :icon, then the value is the state into which the window will be placed if expand-window is called on it or if (setf state) is called on it with the :expanded state. This is also the most recent expanded state that the window was in, or :normal if it has never been expanded. If the current state of the window is :normal or :maximized, the value is the state to which the window was most recently expanded from :shrunk or :icon state.
Here is an example of an added (setf state) :around method that looks at both the old and new states of any frame-window whose state may be changing, and reports any change. Typcially several custom methods on shrink-window, expand-window, and so on in 5.0.1 could be collapsed into such a single (setf state) method. A simpler :after method could be used instead if the old state is not of interest.
The without-package-locks is needed here in a source code file that's not in the common-graphics package only because it specializes a common-graphics method on a built-in common-graphics class; normally an application would specialize on its own subclass instead.
The requested-state argument is ignored because it may be :expanded, and we are interested here in the resulting :normal or :maximized state instead. Similarly, some other (setf state) method could coerce the requested state to something else.
eval-in-listener-thread is used to make sure that the printed output always goes to the selected IDE listener pane (and so this method is suitable only for the IDE and not for a generated application). Otherwise, the message will go to the *terminal-io* of whatever thread changed the window state; for example, clicking the minimize button of an IDE window would iconize the window in the IDE GUI thread, for which terminal-io is bound to the console, and so the output would appear there.
The progn is used to ensure that this (setf state) method returns whatever the next called method returns, though that would normally be the requested-state.
(without-package-locks
(defmethod (setf state) :around (requested-state (window frame-window))
(declare (ignore requested-state))
(let* ((old-state (state window))
new-state)
(prog1 (call-next-method)
(setq new-state (state window))
(unless (eq old-state new-state)
(ide:eval-in-listener-thread
`(format t "~&State of ~s changed from ~s to ~s.~%"
(name ,window) ,old-state ,new-state)))))))State on outline-items
The state property also applies to outline-items, though the valid values are :closed, :open, and :partially-open, rather than the values listed above.
:closed indicates that the item's subitems are not currently shown, while :open indicates that they are. :partially-open indicates that some but perhaps not all of the subitems are currently shown, and so the next user gesture to toggle the state will show all subitems, rather than hiding them as is normally done when subitems are already showing.
:partially-open is probably useful only when a range-on-open method has been supplied for the outline, since a range-on-open method can be written to return different sets of subitems at different times depending on some arbitrary current context.
(setf state) may be called on an outline-item to hide or show its subitems, as an alternative to calling close-outline-item-value or open-outline-item-value; passing :partially-open will show the subitems, but leave the outline-item in a state where the next user gesture to toggle the state will again show subitems. The state of an outline-item may also be established by passing the :state initarg when calling make-instance to create the outline-item.
The (setf state) method for an outline-item does not do certain additional things (that were done is earlier releases) that an interactive toggling of the item state might do, such as moving the keyboard focus to the item and scrolling the item into view. This was especially inefficient when programmatically setting the state of a number of outline-items, and could leave the focus on an arbitrary item. An application can control the extra behavior with calls to the setf's of functions such as focus-index, selected-outline-item, and a call to set-first-visible-line.
Generic Function, cg package
Arguments: list-view-item
Returns (or sets with setf) a non-negative integer or nil, indicating the state pixmap (if any) to display in the argument list-view-item. If an integer, the value is an index into the state-image-list of the list-view widget that this list-view-item is on. Zero indicates the first pixmap in the list. No state pixmap is displayed in this list-view-item if the state-icon-index is nil or an integer greater than or equal to the number of pixmaps in the state-image-list, or if the state-image-list is nil. See also icon-index.
See list-view.
Generic Function, cg package
Arguments: list-view
An image-list instance that contains pixmaps to display in this list-view alongside the main pixmap for each item, or nil to not display state icons in this list-view. When the layout-style of the list-view is either :list or :report, then a non-nil state-image-list will also cause an extra column of space to be reserved to the left of the main icons for displaying the state icons, even if none of the list-view-items actually use any of the state-images. If the state-image-list property is left as nil, then no extra space is allotted for state icons.
State icons are intended to show some temporary state of list-view-items, and may be switched frequently by changing the state-icon-index of individual list-view-items. The main (large and small) icons are intended as more permanent identifiers of various types of list-view-items; they may also be switched at will, though this is somewhat less efficient than switching state icons.
As with small-image-list, this property may alternately be specified as a list of names of cached pixmaps as a shortcut.
A state-image-list typically contains pixmaps that are 16 by 16 pixels in size. They can be other sizes, but may get clipped if larger due to the limited space that is reserved for the icons.
The icons will appear only if one or more of the list-view-items of the list-view have non-nil values for the state-icon-index property.
See list-view.
Generic Function, cg package
Arguments: window
Returns the status-bar of window. Returns nil if window does not have a status-bar.
Generic Function, cg package
Arguments: parent-window
Returns the default font for use in a status-bar or common-status-bar on parent-window.
Generic Function, cg package
Arguments: status-bar string &key part protruding-p no-border-p
Displays string on status-bar, which is either a status-bar or a common-status-bar in which to display the string. The keyword arguments are valid only for common-status-bar's.
The keyword arguments are:
part is either a fixnum indicating the section of the common-status-bar in which to display the string, or the keyword :simple to display the string in simple (non-sectioned) mode, or nil to display the string in the first section (or in the whole status-bar if there are no sections currently). The common-status-bar will be automatically placed in simple mode if part is :simple, or into non-simple (sectioned) mode if part is a fixnum. Zero indicates the first section.
protruding-p if true will draw the section border to make it appear raised, rather than sunken as usual.
no-border-p will draw the string without a border at all around its section. The default is nil.
Generic Function, cg package
Arguments: parent-window
Returns the default number of lines for a status-bar on parent-window.
Generic Function, cg package
Arguments: object
Returns true if the argument is an instance of either the status-bar class or the common-status-bar class, and returns nil otherwise.
Generic Function, cg package
Arguments: timer
Stops timer, which must be an instance of the timer class, from running (if it is running). That is, it makes its active property nil.
If a timer is intended to fire only once after it is started, then stop-timer can be called in the timer's on-timer function to prevent further firings until the timer is restarted. Otherwise stop-timer may be called at any arbitrary time when no further firings are desired.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: stream char &key return-real
Returns the pixel width of the character char when printed onto stream in its current font. stream should be a cg-stream.
If return-real is true, then any non-integer real value is returned as is, and otherwise the result of calling ceiling on the value is returned. When running in a web browser, JavaScript returns real values, and return-real can be used to avoid roundoff errors (especially when multiplying the character widths of a sequence of characters). This parameter was added in release 11.0.
Function, cg package
Arguments: stream
Creates and returns a position object indicating the current origin of stream. The origin is the position on the scrollable page (canvas) of the stream to which the position 0,0 in stream (user) coordinates will map. The origin is specified relative to the upper-left corner of the page. stream should be a cg-stream.
(setf stream-origin) may be called to set the origin to a new position relative to the upper-left corner of the page.
A stream's origin is initially 0,0, meaning that something drawn on the stream at 0,0 will be placed at the top-left of the stream's scrollable page (or simply at the stream's upper-left corner if it is not scrollable).
As an example,
(setf (stream-origin my-stream) (make-position 30 80))would move the origin so that drawing something on the stream at 0, 0 will place it 30 pixels rightward and 80 pixels downward from the upper-left corner of the stream's page. The leftmost and topmost position that may be drawn to would then be the position -30, -80.
It is typically most straightforward to leave the origin of a stream at its initial 0, 0 position, and draw everything at positive coordinates relative to that. One handy use of the origin, however, is to draw a polygon (with draw-polygon) at different locations on the page by setting the stream's origin differently for each location, rather than changing all of the vertices of the polygon.
For a scaling-stream, the stream-origin position is still measured in pixels (device units) rather than in arbitrarily-scaled stream units as other user-level coordinates are.
See also nstream-origin, move-stream-origin, and cg-coordinates.html (especially the section Coordinate System Location of Origin).
Function, cg package
Arguments: cg-stream
Returns the package in which unqualified symbols will be read from and printed to in cg-stream, which should be a cg-stream.
An application may call (setf stream-package) to declare what the package of a cg-stream is. Then whenever certain Common Graphics functions are called that may do a Lisp read on a string that is associated with the cg-stream (or a Lisp write on an arbitrary Lisp object), then *package* will be bound to the stream-package of the stream at that time.
In particular, some methods of selected-symbol and selected-form use the stream-package when reading from strings, and the paste-selection method for text-edit-pane uses it when printing Lisp objects. Other exported Common Graphics functions may call these functions, and the IDE does as well.
The value passed to (setf stream-package) may be either a package object, a package name, or nil to indicate no associated package. When nil, no rebinding of *package* is done. The default stream-package is nil.
Function, cg package
Arguments: stream string &optional start end
Use of the function is deprecated. Use stream-string-width and line-height instead.
Returns as multiple values four position objects defined as follows:
(make-position 0 0)
(make-position 0 (line-height stream))
(make-position (stream-string-width stream string start end) 0)
(make-position (stream-string-width stream string start end) (line-height stream))
See line-height and stream-string-width. The returned values are not meaningful if string (or the substring specified by start and end) contains newline characters.
The results describe the area taken up by string (or the substring specified by start and end) if it were printed to stream using the font of stream as returned by font. stream should be a cg-stream.
Because this function returns the same information as line-height and stream-string-width (though in a somewhat different format), its use is deprecated. We recommend you use line-height and stream-string-width instead.
The function nstream-string-corners is the destructive version of this function.
Function, cg package
Arguments: stream string &optional start end
Use of this function is deprecated. Use stream-string-width instead.
Creates and returns a position object whose position-x is the value returned by stream-string-width (indicating the width in pixels of string when printed in stream) and whose position-y is 0. The size of a substring of string specified by start and end is determined if those arguments are supplied.
stream should be a cg-stream.
Because this function returns the same information as stream-string-width, use of this function is not recommended.
The result is not meaningful if string contains newlines.
nstream-string-size is the destructive version of this function.
Generic Function, cg package
Arguments: stream string &optional start end handle-kerning
Returns the width of string (or the substring of string specified by start and end) if it were printed onto stream by princ using the current font of stream.
stream should be a cg-stream, and generally should be the non-widget window on which you may also draw the string. You could alternately pass the screen, perhaps as a stand-in stream before creating any windows, though there are a few caveats: (1) in CG/JS mode you cannot draw on the screen; (2) in CG/JS mode the screen does not have a font by default, so you must give the screen a font before calling this function on it; and (3) in Windows desktop mode the measurement can even be different for different kinds of windows, so it may be more important to call this function on the actual window on which you will draw the string.
string can be any Lisp string. This function assumes that the string has no newline characters in it. The result is not meaningful if it does contain newlines.
If handle-kerning is true, then the returned width is more precise when running in a Chromium-based web browser. There is no effect in other cases. For efficiency, CG/JS caches the widths of individual characters, and then this function returns the sum of those cached values for the characters in the specified string. But Chromium appears to do some kerning, where the real width of a string can be a little smaller than that sum. To avoid that problem, passing this argument as t will cause this function to ask the web browser for the real width of the whole string. That takes longer due to sending a message to the browser and waiting for the reply, but the result is more precise when needed. This parameter was added in release 11.0.
Methods are defined for all graphical streams (basic-panes, the screen, bitmap-streams, and printer streams).
Generic Function, cg package
Arguments: stream position-or-box
Converts a position or box that is in stream units (offset from its position relative to the physical interior upper left corner of window according to the scroll position and origin of window ) so that it is in device units (directly relative to the physical interior upper left corner of the device, which is often a window).
Destructively modifies the position or box argument.
In earlier releases, this function was named stream-to-window-units. The old name can be used for backward compatibility.
Function, cg package
Arguments: from-window-or-screen to-window-or-screen position-or-box
Converts a position or box from being relative to the logical interior upper left corner of the first window (from-window) to being relative the logical interior upper left corner of the second window (to-window). "Logical" here means that stream units are offset from the physical window position according to the scroll position and origin of the window.
Destructively modifies the position or box argument.
Generic Function, cg package
Arguments: stream position-or-box
The name of this function has been changed to stream-to-device-units. See the description of that function for details. The symbol stream-to-window-units continues to name that function as well, for backward compatibility.
Generic Function, cg package
Arguments: stream
Returns two values; the number of stream units per inch horizontally and the number of stream units per inch vertically. stream may not be a text-edit-window or a text-edit-pane.
setf can be used with this function to change the scale at which drawing is done on certain streams (see below). Initial stream units are in pixels, so, for example, drawing a line from (0,0) to (0, 100) draws a line 100 pixels long. Changing the value returned by this function will make a line of length 100 stream units something other than 100 pixels long.
This makes it possible to redirect output that is usually drawn in a window so that it is drawn on a printer instead without having to scale the drawing coordinates in your own code. Suppose, for example, your monitor has 90 pixels per inch. Then
(setf (stream-units-per-inch my-printer-stream) 90)allows drawing on the printer stream with the same coordinates as drawing in the window and getting an image the same size.
Only streams that have scaling-stream mixin can have their stream-units-per-inch modified. scaling-stream is the parent of the printer class but not of any of the built-in window classes. To make a scalable window, you must create a class with scaling-stream and some window class as superclasses.
See also points-to-pixels and pixels-to-points.
Generic Function, cg package
Arguments: stream
Returns two values; the number of stream units per mm horizontally and the number of stream units per millimeter (mm) vertically. stream may not be a text-edit-window or a text-edit-pane.
setf can be used with this function to change the scale at which drawing is done on certain streams (see below). Initial stream units are in pixels, so, for example, drawing a line from (0,0) to (0, 100) draws a line 100 pixels long. Changing the value returned by this function will make a line of length 100 stream units something other than 100 pixels long.
This makes it possible to redirect output that is usually drawn in a window so that it is drawn on a printer instead without having to scale the drawing coordinates in your own code. Suppose, for example, your monitor has 4 pixels per mm. Then
(setf (stream-units-per-mm my-printer-stream) 4)allows drawing on the printer stream with the same coordinates as drawing in the window and getting an image the same size.
Only streams that have scaling-stream mixin can have their stream-units-per-mm modified. scaling-stream is the parent of the printer class but not of any of the built-in window classes. To make a scalable window, you must create a class with scaling-stream and some window class (like bitmap-window) as superclasses.
Generic Function, cg package
Arguments: window
Returns or sets with setf the stretch mode of window. The stretch mode determines how pixels are combined when using copy-pixels-to-stream to draw a pixmap on window such that the image is smaller in at least one direction. In that case, at least some pixels in the original image will map to a single displaced pixel. The stretch mode determines the color of those pixels.
The modes are:
:black-on-white performs a Boolean AND operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves black pixels at the expense of white pixels.
:white-on-black performs a Boolean OR operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves white pixels at the expense of black pixels.
:color-on-color deletes the pixels. This mode deletes all eliminated lines of pixels without trying to preserve their information.
:halftone maps pixels from the source rectangle into blocks of pixels in the destination rectangle. The average color over the destination block of pixels approximates the color of the source pixels.
CG/JS Note: stretch-mode is re-interpreted in CG/JS mode, where JavaScript image smoothing is enabled when the value is :halftone, and not otherwise. This applies when stretching the pixmap either larger or smaller, rather than only when stretching it smaller as on Windows. The default is :color-on-color in CG/JS mode, and so image smoothing is NOT done by default (unlike the JavaScript default).
Generic Function, cg package
Arguments: grid-widget section
Initiates an interactive stretching of a grid-section. This is called internally when the user left-clicks on the border of section where it crosses a row-sizing-column-mixin or column-sizing-row-mixin section. It could also be called to programmatically initiate the stretch.
Generic Function, cg package
Arguments: grid-widget section subsection count
Invoked when the user clicks near the right or bottom border of a cell, to allow dragging of that border. The cell's row or column should be of class row-sizing-column-mixin or column-sizing-row-mixin for the click to invoke this method.
Generic Function, cg package
Arguments: pixmap-interface
Returns or sets with setf the value of the stretching property of the argument. This property determines whether a bitmapped object will automatically stretch to fit the size of the picture-button or the static-picture widget boundaries but note that this property will have no effect if the image is specified as an icon (via the pixmap-icon property) rather than as a pixmap (via the pixmap-name, pixmap-source, or pixmap property), because icons do not stretch.
Here are the possible values and their effects:
t: bitmapped image will stretch automatically to fit the size of the widget.
nil: bitmapped image will be drawn at the same size that the image was originally defined.
stretching is a property of the button-info, picture-button, and static-picture classes.
Function, cg package
Arguments: text-edit-pane string replacement &key backward case-sensitive globally (line-of-padding 0)
Searches for a string in a text control, and if found replaces one or more occurrences of that string with a second string. If one or more matches were found, then the number of replacements that was done is returned; otherwise nil is returned.
The arguments are:
text-edit-pane is the text-edit-pane or rich-edit-pane to search.
string is the Lisp string to find in the window's text.
replacement is the string with which to replace the search string if found.
backward: if true, then the search is done toward the beginning of the buffer, starting from the character just before the current text cursor position. Otherwise the search is done toward the end of the buffer, starting from the character just after the current text cursor position. The default is nil, meaning do a forward search.
case-sensitive: if true, then a case-sensitive search is done; otherwise a case-insensitive search is done. The default is nil meaning do a case-insensitive search.
globally: if true, then all matches from the starting point to the end or beginning of the buffer are replaced, and the last replacement (if any) is left selected. Otherwise only the next match in the search direction (if any) is replaced, and it is left selected. The default is nil, meaning replace a single match only.
lines-of-padding: when a string match is selected, the window will be scrolled as needed so that at least this many lines of text are visible both above and below the string match (when possible). This allows the user to see additional context around the string match. The value should be a non-negative integer, and the default is zero.
To ask the user interactively for the search and replacement strings, it may be useful to call ask-user-for-string or pop-up-strings-dialog.
Function, cg package
Arguments: text-edit-pane string &key backward start case-sensitive (select t) (lines-of-padding 0)
Searches for the next occurrence of a string in a text control, starting from the current text cursor position. If the string is found, then the index of the first character in the match is returned; otherwise nil is returned.
The arguments are:
text-edit-pane is the text-edit-pane or rich-edit-pane to search.
string is the Lisp string to find in the window's text.
backward: if true, then the search is done toward the beginning of the buffer. Otherwise the search is done toward the end of the buffer. The default is nil to do a forward search.
start: the character index at which the search will begin. If unspecified or nil, it will begin at the current text cursor position. If a range of text is selected, a forward search will begin by default at the end of the range, and a backward search will begin at the beginning of the range.
case-sensitive: if true, then a case-sensitive search is done; otherwise a case-insensitive search is done. The default is nil meaning do a case-insensitive search.
select: if true (the default) and a match is found, then the match is selected. Otherwise the text cursor is not moved, and the match position or nil is simply returned as usual.
lines-of-padding: when a string match is selected, the window will be scrolled as needed so that at least this many lines of text are visible both above and below the string match (when possible). This allows the user to see additional context around the string match. The value should be a non-negative integer, and the default is zero.
To ask the user interactively for the search string, it may be useful to call ask-user-for-string or pop-up-string-dialog.
Function, cg package
Arguments: inner-box outer-box
Returns true if inner-box is contained within outer-box. Any box is a sub-box of itself.
Generic Function, cg package
Arguments: dialog-item
Use of this function is deprecated. Common Graphics now always internally calls this function on all Microsoft widgets, and so there is never a need for an application to call it. Calling this function will now simply do nothing.
Performs what might be called "MS subclassing" on the window of dialog-item. This has nothing to do with CLOS classes, but rather causes Lisp to intercept all low-level messages that are sent to widget windows and are normally handled within the Windows operating system where these widgets are implemented. All low-level Windows events for dialog-item will be passed to the pc:control-procedure generic function. In addition, the keypress and mouse-click events will call an event method for the dialog-item's window and that event.
You need to call subclass-widget only if you want to handle these low-level Windows events that are usually handled by MS-Windows internally. For example, when a user types a new value into an (single-line) editable-text widget, you normally know only what the new string and the old string are; if you want to know what actual key was pressed, then you will need to call subclass-widget and then write an event method on the window to handle the keypress event. Or you may want to intercept a mouse click on a widget even when its value is not changed by the click.
If subclass-widget is called on a widget that is already subclassed, no action is taken and nil is returned, otherwise t is returned.
Function, cg package
Arguments: section subsection-name
Returns a grid row or column object given its name and the grid section that it is in.
See the grid-widget class for an overview of writing grid-widget code.
Generic Function, cg package
Arguments: grid-section
Returns the number of rows or columns that are in grid-section, which is a grid-row-section or grid-column-section.
The setf of this function can be called to add or remove columns to or from the section, passing a non-negative integer for the new total number of columns. If the number is less than the current number of columns in the section, then columns will be removed from the end of the list. If the number is zero, then the section will be removed entirely unless its name is :body. If the number is greater than the current number of columns, then columns will be added to the end of the list. Any new columns that are created will have the property values that are specified in the subsection-defaults of grid-section.
The functions body-column-count, body-row-count, header-column-count, header-row-count, footer-column-count, and footer-row-count are convenience functions that call this one. They can be set interactively as properties in the inspector for grid-widgets that have those typical sections.
Generic Function, cg package
Arguments: grid-section
Returns an object that specifies default property values for the rows or columns of the grid-row-section or grid-column-section passed as the argument grid-section. Setting a property value of this object will set the same property value of each existing row or column of the argument to the specified value. Thereafter, any rows or columns that are added to the section by calling (setf subsection-count) will get their initial property values from this object as well.
This facility allows specifying default values for a grid-widget that are different than the default values of the grid-row and grid-column classes. This is convenient when creating a grid-widget interactively on a form window without defining and specifying subclasses for the parts of the grid-widget (see the tutorial on this in cg-grid-widget-simplified-tutorial.html). Typically in the inspector you would then go to the subsection-defaults property of a grid-row-section or grid-column-section and specify default values for most or all of the rows or columns of that section, and then maybe go to individual rows or columns and specify property values that override these defaults.
The properties of this object can have the same values as the properties of grid rows and columns, and they can also have as a value the special keyword symbol :defer, which means that this "defaults object" is not specifying a default value to use, and so each row or column will default to the value that is specified by the grid-row or grid-column class. The value of each property is initially :defer, allowing you to override only the particular properties that should differ from the class defaults.
The convenience properties body-column-defaults, body-row-defaults, footer-column-defaults, and footer-row-defaults allow you to jump directly in the inspector from the grid-widget to the defaults for the typical body and footer grid sections.
This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.
If you are creating a subsection-defaults object programmatically to assign to a grid-section, it is best to make a column-defaults object for a grid-column-section or a row-defaults object for a grid-row-section. Those are subclasses of the subsection-defaults class that have all of the properties for each grid-subsection subclass. Either class will accept the properties section-size, minimum-size, resizable, proportional, border-width, border-dashing, border-color, section-count, movable, deletable, selectable, device (specified with the :class initarg), and header-background-color. column-defaults will further accept single-line, font, horizontal-justification, vertical-justification, horizontal-padding, vertical-padding, use-lettered-menu, sortable, on-sort-predicate, typable, on-print, title-reader, edit-start-trigger, edit-end-trigger, template-string, template-allows-sign, click-must-be-on-gadget, button-function, button-fills-cell, data-reader, data-writer, data-slot, data-read-converter, data-write-converter, range-reader, font-reader, selected-reader, and available-reader. Some of those column properties apply only to particular column widget classes such as editable-text-column-mixin, but they are all on the subsection-defaults object to be applied to any applicable columns.
Generic Function, cg package
Arguments: grid-widget grid-section
This generic function is called whenever the sequence of grid-rows or grid-columns in a grid-section (a grid-section of grid-widget, a grid-widget) has changed. It is called when the user interactively slides rows or columns to change their order, and when the set of subsections is changed by calls to (setf subsections), add-row, add-column, delete-row, and delete-column.
An application should not call this function, but it may add methods for side effects.
Generic Function, cg package
Arguments: grid-section
Returns a list of the grid-rows of a grid-row-section of a grid-widget, or a list of the grid-columns of a grid-column-section of a grid-widget. The setf of this function may be called to replace the current subsections of a row-section or column-section with a new list of grid-rows or grid-columns that were created with make-instance. This is generally faster than deleting and adding subsections individually by calling delete-row, delete-column, add-row, and/or add-column. An application can know whenever the sequence of subsections has changed by adding methods to subsection-sequence-changed.
subsections is a property of the grid-section, grid-column-section, and grid-row-section classes
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the subtitle property of a chart-or-plot. The value may be set at creation time by passing the :subtitle initarg, or any time later by calling (setf subtitle).
subtitle is a string that is drawn below the main title of a chart-or-plot, typically in a smaller font (see subtitle-font). The value should be a string to display, or else nil to avoid displaying a subtitle. The default value is nil.
If the string doesn't fit onto a single line, then it is wrapped at spaces as needed, and enough space to accomodate the required number of lines is allocated automatically. The string may also contain embedded newline characters to explicitly wrap the text at particular places.
The string is drawn using the subtitle-color and subtitle-font properties of the chart-or-plot.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the subtitle-color property of a chart-or-plot. The value may be set at creation time by passing the :subtitle-color initarg, or any time later by calling (setf subtitle-color).
subtitle-color is the color in which the subtitle of a chart-or-plot, if any, is drawn. The value should be an RGB object (see make-rgb). The default value is the value of black.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the subtitle-font property of a chart-or-plot. The value may be set at creation time by passing the :subtitle-font initarg, or any time later by calling (setf subtitle-font).
subtitle-font is the font in which the subtitle of a chart-or-plot, if any, is drawn. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 12).
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments: symbol-string &optional default-package
Parses the colon (or pair of colons) in a string to return two values: a symbol-name string and a package. If the substring before the colon(s) is not the name or nickname of a package, then nil is returned as the second value rather than a package.
For example:
> (symbol-string-and-package-from-string "cg::dummy")
"dummy"
#<The CG package>Generic Function, cg package
Arguments: widget
Causes widget, which must be a picture-button or a static-picture widget, to re-read its bitmapped image from the file that is named by the widget's title or value (respectively). Normally the image is cached in Lisp, so this is a handy way to update the widget's image if its file has been edited.
Function, cg package
Arguments:
Returns the suggested color for painting the background area of a parent window where it is not covered by child windows and when it contains no other meaningful content. This is one of the colors that the end user sets up in the global control panel, and is typically a darker color than system-dialog-background-color. The IDE uses this color for its background window, for example.
Function, cg package
Arguments:
Returns the color to be used for the interior background of non-dialog application windows, as set up in the Windows Control Panel by the end user. Control Panel preset color schemes generally set this to white, though this color can be changed individually.
Function, cg package
Arguments:
Returns the color to be used for the interior background of dialogs, as set up in the Windows Control Panel by the end user. This is generally light-gray or some other significantly off-white substitute for it.
Function, cg package
Arguments:
Returns the color to be used for text in disabled controls and menu-items, as set up in the Windows Control Panel by the end user. This is generally gray or some other moderately dark substitute for it.
Function, cg package
Arguments:
Returns the color to be used to color 3D edges on the lit sides, as set up in the Windows Control Panel by the end user. This is generally a very light color.
Function, cg package
Arguments:
Returns the color to be used to color 3D edges on the shaded sides, as set up in the Windows Control Panel by the end user. This is generally a fairly dark color.
Function, cg package
Arguments:
Returns the (operating system) system fixed font.
Function, cg package
Arguments:
Returns the (operating system) system font.
Function, cg package
Arguments:
Returns the color to be used to draw regular text, as set up in the Windows Control Panel by the end user. The color is usually black.
Function, cg package
Arguments:
Returns the color to be used to draw the background of highlighted (selected) text, as set up in the Windows Control Panel by the end user.
Function, cg package
Arguments:
Returns the color to be used to draw the foreground of highlighted (selected) text, as set up in the Windows Control Panel by the end user.
Generic Function, cg package
Arguments: basic-pane
If this boolean property is true, then the window named by the argument will have a small button on the left side of its titlebar that invokes a standard menu of commands for minimizing, closing, etc. the window.
The system-menu property may not be changed on an existing window, and must instead be specified with the inspector when designing a window (using a form) or with the :system-menu initarg of make-window. (It can be changed using the inspector when designing a form but not for a running window or control, either in the IDE or in an application.)
Function, cg package
Arguments: grid backp
Moves the keyboard focus to the "next" or "previous" cell within a grid-widget. The "next" cell is defined as follows:
the cell immediately to the right of the currently-focused cell if there is a next cell in the same grid-section,
or else the leftmost cell in the next row down if there is a next row in the same grid-section,
or else the upper left cell in the same grid-section.
If backp is true, then the focus is moved in the opposite direction to what was just described.
The TAB key performs this functionality when a grid-widget has the keyboard focus and the tabstop property of the grid-widget is turned off. (If tabstop is turned on, then the tab key will tab to the next widget rather than tabbing to the next cell within the grid-widget.)
Generic Function, cg package
Arguments: tab-control position-in-tab-control
Returns the tab-id of the tab at position-in-tab-control relative to the upper left corner of tab-control (which must be a tab-control). May be useful when handling mouse click events to determine which tab the user has clicked on.
Generic Function, cg package
Arguments: tab-control tab-id
Returns a box indicating the region occupied by the tab for tab-id on tab-control (which must be a tab-control), relative to the upper left corner of tab-control.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the tab-control property of the argument. The value of the property is a list of two symbols, where the first symbol is the name of the tab-control that dialog-item is on, and the second is the name of the tab on this tab-control that dialog-item is on.
If you are interactively designing a dialog by using a form in the IDE, then dragging a widget completely into a tab will automatically assign the widget to the tab. But if you are creating the widgets programmatically, then you must do the assignment explicitly as shown in the example code on the page for the tab-control class, under the heading Adding widgets to tabs programmatically.
The value is nil if the control is not on a tab-control.
See the description of the tab-control class/control.
Generic Function, cg package
Arguments: widget
Returns two values: (1) the tab-control that the control specified by the argument is on (or nil if not on a tab-control), and (2) a list of the tab-infos of the tab-control that the control is on.
Generic Function, cg package
Arguments: tab-control
Returns an integer indicating the height of each row of tabs on tab-control. tab-height is a property of the tab-control class.
Generic Function, cg package
Arguments: object
Returns true if object is an instance of the tab-info class; returns nil if it is not.
Generic Function, cg package
Arguments: tab-control tab-id
Returns the label that is displayed on tab-id of tab-control.
Generic Function, cg package
Arguments: dialog-item
Returns the value of the tab-position property of the argument.
If the tab key moves focus among controls on a dialog, this property indicates how many tabs are needed to get to this control. Tab position 0 means that control has focus when the dialog is displayed. Tab position 1 means pressing tab once moves focus to the control, and so on.
The setf of tab-position may be called to reposition a control that is already on a dialog. But unlike most properties of controls, it would have no effect to specify an initial tab-position when creating a control by passing a :tab-position keyword argument to make-instance. Instead, the initial tab order of the list of controls passed as the value of the dialog-items argument to make-window is determined by the order of the controls in that list. And the tab-position of a control added to a dialog by calling add-component is determined by the value of the behind argument to add-component.
In Windows, the tab-order of the controls on a parent window is always the same as the front-to-back occlusion order of the controls. This means, for example, that a group-box or tab-control must be positioned in the tab order after all of the widgets that are on it, or else it will cover those widgets. This is handled automatically when designing a form window interactively, but it must be handled by the application when creating a dialog programmatically.
(Note that keyboard shortcuts can be used to jump to a control with a keypress. The keyboard shortcut is defined by placing a tilde (~) before the keyboard shortcut letter. The keyboard shortcut is then Alt-[the letter]. The static-text control cannot have focus so if its value has a tilde before a letter, that provides a keyboard shortcut to the next control in the tab order. See the discussion "Using a static text as a keyboard shortcut to jump to a control" in the static-text entry.)
The Form | Set Tab Order menu command can be used to set the tab position for all controls on a form.
Generic Function, cg package
Arguments: tab-control
Returns the value of the tab-side property of a tab-control widget. The value can be set only at creation time, by passing the :tab-side initarg to make-instance.
This property controls where the row of tabs is placed on a tab-control. The value should be one of the keywords :top, :bottom, :left, or :right to indicate the side of the widget that will display the tabs. The default value is :top. Note that the interior area where widgets should be placed will be different when the tabs are on a different side.
Windows Note: This property has no effect on Windows XP in the usual mode, but does work on Vista. It will work on XP only if Visual Styles are not used (see include-manifest-file-for-visual-styles, though that would produce an older look and feel.
Generic Function, cg package
Arguments: tab-control
Returns two values, the height of each tab row of tab-control, and the width of each tab if tab-control uses fixed-width tabs.
Generic Function, cg package
Arguments: widget &optional previous-p
Moves the keyboard focus to the control that comes just after the specified control in the dialog's tab order. If previous-p is true, then the focus goes instead to the previous control in the tab order. When this would result in moving the focus past the last widget or before the first widget, then the focus movement "wraps" to the control at the other end of the tab order.
When defining a custom lisp-widget, the widget will not automatically know to tab to the next or previous widget when the tab key (or shift-tab) is pressed. To make this happen, a virtual-key-down method for the control should call tab-to-next when the data argument is either vk-tab (for tabbing forward) or vk-backtab (for tabbing backward). (It's an anomaly that a shift-tab gesture is denoted as vk-backtab rather than (shift-key vk-tab).
Generic Function, cg package
Arguments: tab-control
Returns the value of the tab-width property of the argument. This property determines the width (in pixels) for the entire row of tabs in a tab-control widget. Must be a positive integer.
tab-width is a property of the tab-control class.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the tabs property of the argument. The value of this property is a list of distances from the left edge of the control. The distances are measured in pixels for outline and list controls, and in character widths for text-editing controls. These are spacing guides for text whenever tab characters appear in a displayed string. For list controls, these values specify the location of columns when the list control displays multiple columns.
tabs is a property of the outline, dropping-outline, multi-item-list, single-item-list, multi-line-editable-text, text-edit-pane, rich-edit, and rich-edit-pane classes.
If the rich-edit has its tabstop property turned off (the default), then pressing the tab key will insert a tab character into the control's text. If the tabstop property is turned on, then pressing the tab key will move the focus to the next widget, and control-semicolon must be pressed in order to insert a tab character interactively. A comtab or virtual-key-down method could be supplied to make some other keychord insert a tab-character by doing something like
(write-char #\tab rich-edit-pane)See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: tab-control
Returns or sets the value of the tabs-are-draggable property of a tab-control. If this property and the single-line property are both true, then the user can rearrange the tabs within the tab-control by dragging after clicking left on a tab. In the IDE, the Editor uses this to allow you to change the order of the editor buffers. The Debug Window also allows you to change the order of any additional listeners that you've created there with the View | New Listener command.
See the description of the tab-control.
Generic Function, cg package
Arguments: outline
A boolean property of outline controls. If an outline has been given tab positions (via the tabs property), then tabs-clip returns (or sets with setf) whether the text in the indented part of the outline at the left will be clipped off if and when it begins to collide with the tabbed text at the first tab position.
tabs-clip is a property of the outline class.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the tabstop property of the argument. The value of this property can be true or nil. When a dialog is selected, pressing the TAB key can move focus from one control on the dialog to another. If the value of this property is true, pressing TAB will eventually move focus to this control. If the value is nil, this control will be skipped over by the TAB key. See tab-position which determines how many times TAB must be pressed after the dialog first appears before this control is reached (assuming tabstop is true).
If a multi-line-editable-text control has the focus and the user presses the TAB key, then, if the component has the tabstop property turned on, the effect is to move the focus to the next component in the tab order. If tabstop is off (or if the component is just a text-edit-pane window rather than a multi-line-editable-text dialog-item), then a tab character is inserted into the text. In some earlier releases, you could enter a TAB character when the tabstop property is on by typing Shift-Tab. This is no longer true. A TAB cannot be conveniently entered when tabstop is on.
Windows only allows you to tab to a radio-button when it is on. The usual approach is to set the tab order of your dialog so that all of the radio-buttons that are in the same cluster will be adjacent in the tab order, and then make sure that the initial value of one of the radio-buttons in the cluster is non-nil. Then the user will be able to tab to the currently "on" radio-button in that cluster and then use the keyboard's arrow keys to move to the other radio-buttons in that cluster.
Function, cg package
Arguments:
Tells the web browser that the app is exiting. Calling this just before exiting Lisp can be useful for a couple of things: (1) If the user exits the app without closing the browser tab, then when they do close the empty browser tab later the browser will not prompt for confirmation when the "Confirm Exit" option was used. (2) CG will stop intercepting any browser keystrokes that the user might want to use in the empty tab, such as Control+L to move to the browser's URL widget.
Typically there is no need to call this function, because it is called automatically whenever a standalone CG/JS application from a project exits, and whenever the IDE in CG/JS mode exits. But it could be needed when loading CG into a base Lisp or when generating a CG app from scratch without using the project system.
Generic Function, cg package
Arguments: editable-text
Returns whether the user is allowed to type a plus or minus character in an editable-text widget that has a template-string. The value may be set at creation time by specifying the template-allows-sign initarg, or any time later by calling (setf template-allows-sign).
This property is used only with a template-string. When true, the user may type a plus or minus character in any template character position where there is no template character position to the left that contains a non-space.
Generic Function, cg package
Arguments: editable-text
Returns the template for a single-line editable-text control, which constrains the number and type of characters that a user can type into the control. The value can be set at creation time by specifying the template-string initarg, or any time later by calling (setf template-string).
A template consists of two kinds of characters:
static characters that are shown in the control and over which users cannot type (the cursor is moved past these characters as the user types or uses the arrow keys).
template characters, which must be described in the *template-chars* association list (any character not in this alist is regarded as a static character). Initially the template characters appear as blank spaces, zeroes, or other default characters in the control and allow users to enter certain types of characters depending on which template character is specified for each position.
Templates can be cleared with clear-template.
(setf (template-string my-editable-text-widget) "999-99-9999")This example would set up a template for entering a social security number. There is an entry in *template-chars* for the character #\9 indicating that a user must enter a numeral in its position, and that it displays initially as a space. There is no entry in *template-chars* for the dash character, so the dashes in this template will display as dashes, and users cannot type over them.
template-string is a property of the editable-text class, as well as the editable-text-column-mixin and combo-box-column-mixin
When a graphical character is typed, it will be considered for the character position at the text cursor if there is a template character rather than a static character at that position. Otherwise it will be considered for the first position to the right of that position at which there is a template character, if any. If the typed character passes the predicate function for that position, then it will replace the character at that position. The text cursor will then move to the next template character position to the right, if there is one, and otherwise will move to the rightmost end of the template string. When the character is not valid at the current position, there is a beep and nothing else is done.
A special case is that if the text cursor is at the rightmost end of the template string, then typing a character will shift each character that has already been typed one template character position to the left, and then the new character is written to the rightmost template character position. This is typically used for entering numbers as with a calculator or ATM machine.
If any text is selected when a graphical character is typed, then the selected characters are first converted (cleared) to the initial print characters for those positions, then the text cursor is moved to the front of the selection (deselecting the text), and then the character is handled as above. An exception is that if the justification of the widget is :right and all of the text is selected, then the text cursor is moved to the end of the selection rather than to the front.
The left and right arrow keys will move the text cursor to the next template character position in each direction if there is one, or else to front or end of the template string if it is not there already. Pressing the left and right arrow keys while holding down the Shift key will select text as usual.
The Home key will move the text cursor to the first template character position that does not have a space in it, unless the text cursor is already in that posiiton, in which case it will move to the first template character position. (In other words, typing Home will first move to the beginning of the text that has been entered, and typing it again will move to the first typable position. That is intended to be useful especially when editing right-justified numbers.) Similarly, typing End will first move the text cursor just to the right of the last template character position that does not contain a space, unless the text cursor is already at that position, in which case it is moved just after the last template character position.
The Delete key will change the character at the text cursor to the initial print character for that position and move to the next template character position to the right. The Backspace key will move to the next template character position to the left and change the character at that position to the initial print character for that position. A special case is that typing Delete when the text cursor is at the rightmost end of the template string will delete the last character by shifting all other typed characters one position to the right.
If the template-allows-sign property of the widget is true, then the user will be allowed to type a plus or minus character in any template character position that is to the left of all non-space typed characters.
Function, cg package
Arguments: symbol
Returns (or sets with setf a list of integers that specifies how a source code form whose first element is symbol will be indented in the IDE editor if the form is wrapped to multiple lines. Each integer in the list specifies the number of spaces to the right of the form's opening parenthesis by which a corresponding element of the source code form will be indented if it begins a line of source code. The first integer corresponds to the second element of the source code form (typically the first argument to a function), the second integer corresponds to the third element of the form, and so on. The last integer in the list is also used for all leftover elements of the form when the form is longer than one plus the length of the integer list.
For example,
(text-edit-indentation 'defclass) returns the list
(4 4 2)That indicates that the name of the class and the list of superclasses will each be indented by four spaces when they occur at the beginning of a line, and the rest of the defclass form will be indented by two spaces.
text-edit-indentation returns nil when no indentation has been specified for a symbol, and the IDE editor uses a default indentation for forms beginning with that symbol. If a newline exists after the first element of a form (or if the first element of the form is not a symbol), then the default indentation is one space. Otherwise successive lines are aligned to the right of the form's initial symbol.
This facility is not nearly as powerful as it might be. For example, there is no way to make a defmethod form indent its parameter list by a certain amount regardless of whether the form contains a qualifier (such as :after) before the parameter list. So this feature may be enhanced in the future, and enhancement may be incompatible. For now, certain definers such as if* and loop have hardcoded indentation styles since this general specification is not adequate.
text-edit-indentation specifications are provided for many symbols, but users may want to add specifications for additional symbols, especially their own. This may be useful for function or macro names whose first one or two arguments are special in some way and indenting these arguments differently may clarify their special status. It may also be useful for reducing overall indentation when some arguments are placed on the same line as a defining symbol, since the default is to align successive lines at the far right of the defining symbol.
Generic Function, cg package
Arguments: text-edit-widget-or-window
Returns a value indicating the extra empty space that will appear in a text-editing control between its left and right borders and its text. The setf of this function may be called to change the margins at any time, and the margins may be specified initially as the value of the :text-edit-margins initarg when creating the control. The control will be redrawn as needed automatically whenever these margins are changed.
text-edit-widget-or-window may be either an editable-text or multi-line-editable-text widget or an editable-text-pane or text-edit-pane window. For the widgets, text-edit-margins appears as a property in the inspector when laying out widgets interactively on a form.
The value that is returned from text-edit-margins or passed to (setf text-edit-margins) may be either nil to indicate default margins, or a non-negative integer to specify the same margin for both sides, or a list of two non-negative integers to specify individual margins for the left and right sides (in that order). The values are measured in pixels, and are added to any default margins that are built into the control. nil and 0 and (0 0) are equivalent values that indicate default margins. The initial value is nil.
This function determines how a text-editing control lays out its interior, and so is distinct from other margin-related facilities that affect how stream output is printed, such as the Common Lisp variable *print-right-margin* and the Common Graphics functions left-margin, top-margin, right-margin, and bottom-margin.
Generic Function, cg package
Arguments: text-edit-pane
This function is used only in CG/JS mode. An application could add methods that return true for text-edit-pane subclasses that implement custom handling when the user types the Enter key, where the browser widget should not directly add a newline character.
CG/JS generally lets the web browser directly handle keystrokes in a text-edit-pane to immediately add typed characters to the widget and move the text cursor around and so on. Otherwise text editing would likely be sluggish if every keystroke were sent to the CG server and then the CG server told the browser widget to programmatically insert a character or move the text cursor.
But the browser still sends most keystrokes to the CG server after that, for any side effects that an application implements. So virtual-key-down methods will still be called for a text-edit-pane.
But sometimes an application may need to handle the Enter key entirely itself, without letting the browser add a newline character at all. When that is the case, adding a method to this generic function that returns true for that text-edit-pane subclass will prevent the browser from inserting the newline character before it sends it to the CG server. If what the application does with the keystroke includes inserting a newline character at some point, then the CG code needs to do that itself, such as by calling insert-character.
CG will prevent the browser widget from inserting any typed characters until the CG application is done handling the Enter key, and then the browser will insert the typed characters that were queued up. This prevents characters from being inserted in the wrong order.
Generic Function, cg package
Arguments: stream line-number
stream should be a text-edit-pane window or multi-line-editable-text widget.
line-number should be a non-negative integer indicating which line of text to return, where zero indicates the first line of text.
The line number could be derived by calling a function such as current-line-number, line-number-from-char, or number-of-text-lines.
Generic Function, cg package
Arguments: multi-line-text-widget-or-window start end return-crlf
Returns a string consisting of the text from index start to index end in either a multi-line-editable-text control or a text-edit-pane. If either start or end are outside the range of zero to the length of all the text, these indices are constrained to be within that range, and the length of the returned string will then be less than (- end start).
The return-crlf argument no longer has any effect, and is kept for backward compatibility only. It was used on the Windows platform by an earlier version of the RichEdit control.
The length of the actual returned string is returned as a second value.
Generic Function, cg package
Arguments: standard-object
Returns (or sets with setf) the texture used by a pixmap or mouse cursor (specified by the argument). The texture is a standard object that defines the array of pixel values for the pixmap. The data for a texture is stored internally as a Lisp array, the platform- and version-independent interface to the texture is the nested set of lists of pixel values stored in its contents property. The array is the value of the texture-array property. See also the texture class.
Generic Function, cg package
Arguments: texture
Returns (or sets with setf) the Lisp array that is used internally to draw texture. The element type and bit ordering of this array may differ across various platforms and Allegro versions, so it is better to specify the pixel values by using the platform- and version-independent contents property than by using the texture-array property.
texture-array is a property of the texture class.
Generic Function, cg package
Arguments: texture
Returns the height in pixels of the Lisp array that is used internally to draw the pixels of texture. texture-array-height is a property of the texture class.
Generic Function, cg package
Arguments: texture
Returns the width in pixels of the Lisp array that is used internally to draw the pixels of texture. texture-array-width is a property of the texture class.
Generic Function, cg package
Arguments: pixmap
A texture is a pixel-map or bitmap packaged up to work on a particular device. It is used to denote a pattern to fill an area of a stream or background, and to define cursors. A texture is not associated with a particular stream. If it is a pixel-map, the specified colors are used. In the case of a bitmap, value 1 is interpreted as the stream foreground color and the value 0 as its background color. A texture-info is the structure associated with the texture.
This function returns the texture-info associated with pixmap. texture-info is a property of the pixmap class.
Function, cg package
Arguments: struct
Returns or sets with setf the bits per pixel of the texture-info that is the value of the argument.
Function, cg package
Arguments: struct
Returns or sets with setf the array of colors of the texture-info that is the value of the argument.
Function, cg package
Arguments: struct
Returns or sets with setf the height of the texture-info object supplied as the argument.
Function, cg package
Arguments: struct
Returns or sets with setf the value of the invert-p attribute of the argument, which must be a texture-info object.
Function, cg package
Arguments: struct
Returns or sets with setf the width of the texture-info object supplied as the argument. See make-texture-info.
Function, cg package
Arguments: struct
Returns or sets with setf the value of the x-device-units-per-m slot of the texture-info object supplied as the argument. See make-texture-info.
Function, cg package
Arguments: struct
Returns or sets with setf the value of the y-device-units-per-m slot of the texture-info object supplied as the argument. See make-texture-info.
Generic Function, cg package
Arguments: texture
Returns true if the argument is an instance of the texture class. Returns nil if it is not.
Generic Function, cg package
Arguments: check-box
Determines whether :gray is a third meaningful value for the argument check-box, which should be a check-box instance.
The default value is nil, in which case the check-box will be blank when its value is nil and otherwise will show a check mark. Clicking on the check-box will toggle its value between nil and t (unchecked and checked). Other equivalent action such as selecting and pressing the Space bar will also toggle between checked and unchecked.
If this method returns a non-nil value other than the value :except-interactively, then the check-box will show a third grayed-out state when its value is :gray. This intermediate state is typically used either to indicate that a true-or-false value is unknown or undetermined, or that some but not all of a set of subchoices are selected. Clicking on the check-box will cycle its value between nil, t, and :gray (in that order).
If the value returned by the method is the keyword :except-interactively, then the check-box's value may be set to :gray programmatically by calling (setf value), but interactive gestures (clicking the check-box or pressing the spacebar when it has the keyboard focus) will only toggle the value between t and nil. If the value is :gray, clicking will change it to t (checked) and then toggle between t and nil. (This value may be useful when you want the gray state before any user action on the check box at all, but once the user acts, the only choices are checked and unchecked.)
This property cannot be changed on an existing check-box (except in the inspector for a check-box on a form designing a dialog). The only way to specify the value programmatically is to pass the :three-state argument when calling make-instance to create the check-box.
Generic Function, cg package
Arguments: scroll-bar
Returns the value of the thumb-length property of scroll-bar controls (vertical-scroll-bar and horizontal-scroll-bar). Its value is either a positive integer that indicates how large the "thumb" (also called the elevator or scroll-box) of the scroll-bar should be, or else nil to use a default size. The thumb will be drawn such that the length of the thumb compared to the length of the rest of the interior scroll-bar length is proportional to the thumb-length property compared to the size (scroll-max - scroll-min) of the scroll-range property.
If a scroll-bar control is being used to scroll a portion of some drawing into a scrollable area (as window scrollbars do), then typically an application would set the thumb-length to the size of the visible area and scroll-range to the size of the portion of the picture that does not fit within the visible area. Otherwise the thumb-length may not be relevant, and the default size (where thumb-length is nil) may be best.
In releases prior to 6.0, this property was called visible-portion. That symbol still names this function (and the :visible-portion initarg is still accepted), but use of visible-portion is deprecated. Further, the meaning has changed somewhat.
In releases prior to 6.0, the range of a standalone scroll-bar control included the thumb-length (then called visible-portion), which made it similar to the whole page of a scrollable window rather than the scrolling range (which is the page minus the visible portion of the page). This was an inconsistent usage of the Common Graphics scroll-range concept. It also meant, for example, if the range of a standalone scroll-bar control was 0 to 100 and the thumb-length was 20, then the possible values of the scrollbar actually ranged from 0 to 80 rather than the alleged range of 0 to 100. Starting in release 6.0, the range no longer includes the thumb-length.
It is not possible to disable a scroll-bar dialog-item by setting its thumb-length to be greater than or equal to the range. You can disable a scroll-bar control by setting the range with the min value equal to the max value, such as (0 0). (Also, as with other controls, scroll-bars may be disabled by setting its available property to nil.)
Generic Function, cg package
Arguments: trackbar
Returns or sets with setf the value of the tick-frequency property of the argument. This value of this property should be an integer. Tick marks will be placed tick-frequency width apart on the control. For example, if the range is (0 50) and tick-frequency is 6, tick marks will be placed at 6, 12, 18, 24, 30, 36, 42 and 48, along with marks at the beginning and end of the range.
The tick-side property determines where the tickmarks appear (and can be :none, in which case no tcikmarks appear). See also tick-position.
tick-frequency is a property of the trackbar class.
Generic Function, cg package
Arguments: trackbar value
Returns the number of pixels from the left edge (or bottom edge if orientation is vertical) of trackbar to value (which should be in the range of trackbar). This value may be useful for determining where to position a label under a tick mark. (A trackbar does not include tick labels.) See the description of the trackbar class/control.
This property is not setf'able.
Generic Function, cg package
Arguments: trackbar
Returns the value of the tick-side property of the argument. The possible values are :left and :top (which, as we explain below, are equivalent), :right and :bottom (also equivalent), :both, and :none.
A trackbar can be oriented horizontally or vertically. Tick marks provide a scale for the trackbar. Therefore :left and :right are appropriate for a vertical orientation while :top and :bottom are appropriate for a horizontal orientation. However, to avoid errors when the orientation is changed, if :left is specified for a horizontal trackbar, it is interpreted to mean :top, and :right is interpreted to mean :bottom. Similarly, if :top or :bottom is specified for a vertical trackbar, it is interpreted as :left or :right respectively.
The trackbar pointer points toward the side with the ticks. If there are ticks on both sides, the pointer does not have a point (it is squared on both sides. If there are no ticks, the pointer points right or down.
The tick-frequency property determines the spacing of tick marks. See also tick-position.
The tick-side property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :tick-side initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)
tick-side is a property of the trackbar class.
Generic Function, cg package
Arguments: timer
This generic function is invoked to "fire" a timer whenever the timer is active and its interval has elapsed. The default timer method increments the timer's timer-count and then calls the timer's on-timer function if it has one. Methods could be added to the timer generic function by an application that wishes to modify the firing behavior of a whole timer subclass, rather than providing an on-timer function to each instance of that subclass.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: timer
This function returns a non-negative integer indicating the number of times that a timer's interval has elapsed since it was most recently started. This value is supplied for general information, and is not used internally by Common Graphics. An application could modify this value if desired, though there is probably no reason to do so.
When a timer is started, this property is set to zero. Each time a timer's interval has elapsed, the default timer method increments the timer's timer-count by one and then calls its on-timer function. If a timer count reaches 500 million, it is reset to zero to prevent the consing of bignums.
timer-count is a property of the timer class.
See cg-timers.html for more information on timers.
Generic Function, cg package
Arguments: timer
This generic function provides a place for an application to store arbitrary information about its current use of a timer. Typically, when an application starts a timer, it will store an object here to which the timer's on-timer function may (or may not) apply its functionality when it is invoked.
The value of this property, which can be set with setf and this function, can be any Lisp object.
(The timer class can of course be subclassed in order to add custom slots for this or any other purpose, but this single timer-info slot is provided since such a handy place is often needed due to the asynchronous nature of timers, and a single slot is often sufficient.)
timer-info is a property of the timer class.
See cg-timers.html for more information on timers.
Function, cg package
Arguments: timer
Returns the process in which timer was most recently started, or nil if it has never been started. This is the process in which the timer's events will be handled (see on-timer).
timer is a timer instance, as created with make-instance.
Generic Function, cg package
Arguments: timer
Returns the universal time at which timer (a timer) is scheduled to fire, or nil if the timer is not currently active.
Since universal times are measured in seconds, this is not useful for timers that have a sub-second interval.
Generic Function, cg package
Arguments: standard-object
Returns (or sets with setf) the value of the title property of the argument. The value of this property generally should be a string. Use the empty string if you want no title. The value nil will display as "nil".
If the object is a menu-item, then the value may alternately be a pixmap to display the pixmap on the menu when running in Windows desktop mode. In other modes what is displayed for a pixmap is undefined, so you should use a pixmap only when a call to js-mode returns true.
For devices such as windows the title will be displayed in some way (on the title-bar, for instance). For buttons, the title labels the button. Some widgets have no place for a title and do not have a title property. If you want to simulate a title, use a static-text widget that's next to the widget.
See also name, but do not confuse name with title. The name is an internal handle for an object (generally a symbol), while the title is a visible label.
Generic Function, cg package
Arguments: basic-pane
Returns the value of the title-bar property of the argument. The value of this property should be t if an object should have a title-bar and nil if it should not. Many windows display what looks like a title-bar even when the property is nil but the title-bar in that case will not have any controls (such as a close box).
The title-bar property may not be changed on an existing window, and must instead be specified with the inspector when designing a window (using a form) or with the :title-bar initarg of make-window. (It can be changed using the inspector when designing a form but not for a running window or control, either in the IDE or in an application.)
Function, cg package
Arguments:
Returns the height (in pixels) of a window title-bar, according to the current Control Panel.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the title-color property of a chart-or-plot. The value may be set at creation time by passing the :title-color initarg, or any time later by calling (setf title-color).
title-color is the color in which the main title of a chart-or-plot, if any, is drawn. The main title is held in the title property that is common to most widgets. The value should be an RGB object (see make-rgb). The default value is the value of black.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the title-font property of a chart-or-plot. The value may be set at creation time by passing the :title-font initarg, or any time later by calling (setf title-font).
title-font is the font in which the main title of a chart-or-plot, if any, is drawn. The main title is held in the title property. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 18).
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: calendar-widget
The number of extra blank pixels to add vertically between the title and the body of a calendar widget.
See also the calendar class and the function ask-user-for-date.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the color of the title of the argument lamp when it is off. The value must be a color object, such as returned by make-rgb. The default value is the value of the symbol black.
See the description of the lamp control.
Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the color of the argument lamp's title when the lamp is on. The value must be an RGB color object, as created with make-rgb. The default value is the value of the symbol black.
See the description of the lamp control.
Generic Function, cg package
Arguments: check-box-column-mixin
An accessor on a check-box column (an instance of a subclass of grid-column and check-box-column-mixin) of a grid-widget. Returns (or sets with setf) the name of a function which will be called in order to obtain the string to display in each check-box grid cell. A title-reader may also be nil rather than a function, in which case no string is displayed and the check-box gadget is centered horizontally in the grid cell. The default value is nil.
The function should take an arbitrary grid-row's data-object as its only argument, and return a string to display in that row. For example, here is the title-reader function for the "Full Time?" column of the employee grid example on the Examples tab of the Navigator dialog:
(defun full-time-p-title-reader (employee)
;; Show a string such as "Trent's full-time"
;; beside the check-box.
(format nil "~:(~a~)'s full-time" (name employee)))Generic Function, cg package
Arguments: lamp
Returns or sets (with setf) the title side of the argument lamp, that is the location of the lamp title with respect to the lamp. The possible values are :center, :right, :left, :top, and :bottom, and nil. When nil, no string is drawn. When :center, the title string is drawn within the lamp image; this generally looks nice only when the lamp-shape is :rectangle and the lamp image is large enough to contain the string. The default value is :right.
See the description of the lamp control.
Function, cg package
Arguments: track minute second frame
Converts the four values specifying the track, minute, second, and frame to a single integer suitable to be used by an MCI device whose time format is :tmsf.
For finer control over device operation, various optional keyword arguments are provided by the methods. For example, to play the first minute of the third track on the cd:
(mci-device-set-time-format cd :tmsf)
(mci-play cd :from (tmsf-to-integer 3 0 0 0)
:to (tmsf-to-integer 3 1 0 0)The above code first tells the device to use the track-minute-second-frame (:tmsf) time format for describing its current location, and then tells the CD to play from "track 3 minute 0" to "track 3 minute 1". (The function tmsf-to-integer is required because there are various time formats that use different numbers of components.) To determine the current position of the CD device while it is playing, use:
(multiple-value-setq (track minute second frame)
(integer-to-tmsf (mci-device-current-position cd)))See cg-mci.html for information about MCI support in Common Graphics.
Function, cg package
Arguments: text-edit-pane
Toggles the bold state of text-edit-pane (a text-edit-pane) by calling (setf bold) with the opposite of whatever bold returns. This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.
Function, cg package
Arguments: text-edit-pane
Toggles whether text-edit-pane (a text-edit-pane) is currently showing bullets by calling (setf numbering-style) with the opposite of whatever numbering-style returns (either :plain or :bullets). This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.
Function, cg package
Arguments: button-widget
Sets the value of a boolean widget to t if its current value is nil, and otherwise sets its value to nil. The boolean widgets (ones that have only two logically distinct values) include button, default-button, cancel-button, picture-button, check-box, and radio-button.
This function emulates clicking on a boolean widget, and is handy for triggering the on-change function of a simple button widget. (Note that while a simple button widget has only a single visible state, it still holds a boolean value that causes the on-change function to run when it is changed.)
Function, cg package
Arguments: text-edit-pane
Toggles the italic state of text-edit-pane (a text-edit-pane) by calling (setf italic) with the opposite of whatever italic returns. This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.
Function, cg package
Arguments: text-edit-pane
Toggles the underline state of text-edit-pane (a text-edit-pane) by calling (setf underline) with the opposite of whatever underline returns. This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.
Function, cg package
Arguments:
Returns the height of toolbars that are created by add-toolbar. In Windows desktop mode this returns *toolbar-icon-height*, while in CG/JS mode it returns *toolbar-icon-height-js*. Those variables could be modified to use a different toolbar height, but this function should be called to return the height in any mode.
Generic Function, cg package
Arguments: object
Returns true if the argument is an instance of the toolbar class. Returns nil if it is not.
Generic Function, cg package
Arguments: window
Returns a list of toolbars on window.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the tooltip property of the argument. The value of the tooltip property should be a (short) string or nil. If the value of the tooltip property of an object is a string, that string will be displayed in a tooltip (a small window) when the mouse is over the object (assuming tooltips in general are displayed, see show-tooltips). If the value is nil, no tooltip is displayed.
A tooltip may be given to a widget (dialog-item), a hotspot, or a button-info of a multi-picture-button widget. A tooltip can be set either by passing it as the value of a tooltip initarg to make-instance, or by calling (setf tooltip) later.
A lower-level function for showing a tooltip at an arbitrary time and place is show-tooltip-explicitly.
Generic Function, cg package
Arguments: configuration
Returns or sets with setf the value of the tooltip-delay property of configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*). The value of this property is a positive integer, initially 1000. This value is used internally by a timer object whose name is :tooltip-timer.
A tooltip will only be displayed after the cursor has been over an object for the tooltip-delay number of milliseconds. However, once one tooltip has been displayed on a control containing sub-controls (such as a multi-picture-button), other tooltips on the same control will be displayed without a delay.
For example, if tooltips are displayed on your system at all, moving the mouse over a button in one of the toolbars in the Project Window displays the tooltip for that button after the delay. But then moving the mouse over other buttons on that toolbar causes their tootips to be displayed at once.
Function, cg package
Arguments:
The font used in tooltips.
Generic Function, cg package
Arguments: component
Returns an x coordinate for the horizontal center of component's tooltip.
The default method centers the tooltip horizontally with its component. An application may modify this generic function if it desires to position tooltips differently for some component.
Generic Function, cg package
Arguments: component
The default method positions the tooltip below the component with a vertical gap equal to
(tooltip-vertical-offset (configuration *system*))(See tooltip-vertical-offset, configuration, and *system*.) An application may modify this generic function if it desires to position tooltips differently for some component.
Generic Function, cg package
Arguments: configuration
The number of pixels below an object that its tooltip will appear. This configuration value is used whenever the default tooltip-top method is in effect. The default value of 16 is somewhat large to prevent the mouse cursor from obscuring the tooltip. A smaller value could be used to position tooltips at a more typical distance for Windows applications.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the top property of the argument. This value is the position of the uppermost edge of bounding box of an object (the visible top if the object is rectangular with a horizontal upper edge). The units are pixels.
Generic Function, cg package
Arguments: standard-object
Returns or sets with setf the value of the top-attachment property of the argument. The top-attachment property of an object determines which edge of the parent window the top edge of the object will follow whenever the parent window is resized. See also bottom-attachment, left-attachment, and right-attachment.
The possible values and their effects are:
:bottom: object maintains a constant distance between its upper edge and the lower edge of its parent window whenever that window is resized.
:scale: object maintains the same ratio of the distances from the top and bottom sides of its parent window whenever that window is resized. I.e., if the top edge was halfway between the top and bottom sides of the dialog before resizing, then it is still halfway between them after resizing.
:top: object maintains a constant distance between its upper edge and the upper edge of its parent window whenever that window is resized.
See also left-attachment, right-attachment, bottom-attachment, track-limits and resize-window.
Function, cg package
Arguments: clipboard-format
Returns the most recent clipboard value of the specified clipboard-format, which may be either :text, :rich-text, or :pixmap (as with clipboard-object).
This function may be useful, for example, if you would like to retrieve the pixmap that was most recently on the clipboard, but the clipboard string was set more recently and this removed any pixmap from the OS clipboard and moved it from the top of the Lisp clipboard stack.
Generic Function, cg package
Arguments: text-edit-pane
Returns the current indentation of the first line of a paragraph of text in a text-edit-pane, or the indentation indicated by the corresponding upper-left slider of a rich-edit-ruler.
This generic function may be called either on a text-edit-pane (typically a rich-edit-pane) or on a rich-edit-ruler. The methods behave somewhat differently: for a text-edit-pane, body-left-indentation is relative to top-left-indentation to match the rich text specification and the Microsoft rich edit control; for a rich-edit-ruler, top-left-indentation is instead relative to body-left-indentation to match the intuitive practice of moving the overall indentation of one or more paragraphs without changing the relative indentation of the first line of each paragraph.
The text-edit-pane method returns the left indentation of the first line of the paragraph that contains the text-edit-pane's text cursor (or the first paragraph partly or wholly contained in the selected text, if any). This value is measured in points, and is measured rightward from the interior left of the text-edit-pane. A point is one seventy-second of an inch.
The setf method for text-edit-pane sets the indentation of the first line of the paragraph that contains the text cursor (or all paragraphs that are partly or wholly selected, if any). Since the body-left-indentation of a text-edit-control is relative to this position, the body indentation will change by the same amount. If there is a rich-edit-ruler associated with the text-edit-pane (see the function ruler), then the rich-edit-ruler's indentation will be automatically modified to match.
The rich-edit-ruler method returns the position of the slider at the upper left of the ruler, measured rightward in points from the position of the lower-left slider for body-left-indentation.
The setf method for rich-edit-ruler moves the upper-left slider of the ruler to the specified position relative to the lower-left slider. The slider will be constrained at position 0 (the leftmost position) if an attempt is made to move it to a negative position. If there is a text-edit-pane associated with the ruler (see the function rich-edit), then the paragraph in the text-edit-pane that contains the text cursor (or all paragraphs that are partly or contained in the selected text, if any) will be automatically modified to match (by modifying indentation of only the first line of each selected paragraph).
To apply this function to a rich-edit control, first apply window to the control to obtain a rich-edit-pane to pass to this function.
To read or modify multiple paragraph attributes of a text-edit-pane at once, see get-paragraph-format or set-paragraph-format.
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: window &key owner-p
Use of this function is deprecated in favor of child-p (which returns the opposite of what this function returns, so replace calls to top-level with (null (child-p ...))). This function is maintained for backward compatibility.
Generic Function, cg package
Arguments: dropping-outline
This property of dropping-outline controls affects the behavior when the dropping-outline is opened in such a way that the dropped outline would extend below the interior bottom of the top-level window that the dropping-outline is in.
If the value of this property is nil, the outline will be clipped at the interior bottom edge of that top-level window. If true, the outline will extend freely past the bottom of the top-level window.
The default value is t. There is likely no good reason to specify nil except for a speed increase that may no longer be perceptible on today's machines. (In releases prior to 7.0, the default value was nil.)
top-level-dropper is a property of the dropping-outline class.
Generic Function, cg package
Arguments: window &key owner-p
Finds the ancestor window of window that is a top-level window. If owner-p is nil, then that top-level window is returned. If owner-p is true, then the owner of the top-level window is returned if it has one, and otherwise the top-level window itself is returned.
See About child, parent, and owner windows in cgide.html.
Generic Function, cg package
Arguments: graphical-stream &optional (stream-units-p t)
Returns the current top margin of a graphical-stream, measured from the top edge of the stream. The top-margin is initially zero, except as noted below. (setf top-margin) may be called to set the margin at any time.
If stream-units-p is true, as it is by default, then the margin is measured in pixels. If nil, it is measured in text line heights (see line-height).
Margin attributes are provided primarily to allow an application to keep a drawing within arbitrary margins by drawing everything within the coordinates returned by left-margin, top-margin, right-margin, and bottom-margin. Common Graphics also uses them in a few special ways, though, as described below.
When opening a printer stream or calling new-page to advance to the next printed page, the current-position-x of the stream is set to its left-margin, and the current-position-y is set to its top-margin.
A printer stream's coordinate system has position (0, 0) at the printer-physical-offset of the printer. To allow an application to avoid dealing with this arbitrary offset, Common Graphics sets the margins of a printer stream to the distance from the physical offset to the margins selected by the user in the print job dialog or page setup dialog. This allows the application to maintain the requested paper margins by simply drawing everything within the four margins that were set up automatically. See *default-printer-left-margin* for more information.
Generic Function, cg package
Arguments: window
Returns the value of the topmost property of a basic-pane. Applicable only to top-level windows (those windows whose parent is the screen). If true, then window will always stay in front of all non-topmost top-level windows (assuming that window is itself a top-level window; topmost has no effect for a non-top-level window).
May be specified with the :topmost initarg as usual with properties. You can setf the topmost property of a window in order to change whether it is a topmost window. One exception is that if you turn on the topmost property of a form, the form itself will not be topmost, but its running window will be.
Care should be taken when making an owned (overlapped or pop-up) window be topmost, because this can lead to the owned siblings of the window becoming non-contiguous in the occlusion order; that is, some of the sibling owned windows may come in front of another application while others stay behind it. For example, if you make a window whose parent is the development-main-window in the IDE, it will be an owned top-level window (since the development-main-window defines an is-child-allowed method to force all of its descendents to be owned windows rather than child windows). If you further make this window be a topmost window and then expose and hide the window (perhaps with pop-up-modal-dialog), then you may find that returning to Allegro from another application exposes only a single selected IDE window.
Therefore, if you make an owned (overlapped or pop-up) window (which provides modality with respect to all of its sibling owned windows) for use as a modal dialog and wish the dialog to also be topmost, then it is recommended that you turn the topmost property on just before calling pop-up-modal-dialog and turn it back off just after.
Generic Function, cg package
Arguments: window touch-points count
This generic function is called one or more times for any gesture on a window if register-touch-window has been called to switch that window to the touch interface. (Otherwise gesture-event will be called by default.) This function will be called once for each different position of one or more fingers during a continuous gesture. This is the somewhat lower-level interface that does not figure out which type of gesture is being done for you, but you can interpret any sort of touches and drags of up to ten simultaneous fingers however you like.
An application can supply methods for this generic function to handle gestures. If a method handles a gesture, it should return true. Otherwise it should return nil to perform the default behavior that's built into Windows. The default method on basic-pane does nothing and returns nil.
window is the window where the gesture began.
touch-points is a vector of touch-point Lisp structures, and count is the number of structures in the vector. Each touch-point is for one of the fingers that are currently touching the screen, and provides a variety of information about that finger.
Note that these structures and the vector containing them are reused on each call to touch-event for the same window. (This is done to reduce consing.) So if you want to save any of this information then you need to extract it from the touch-points and save it elsewhere. Typically you will want to save the X and Y coordinates from the first call for a gesture, or all calls, to compare the coordinates of later calls to them.
Here are the accessor functions of the touch-point structure that a touch-event method can read to determine the current state of a gesture.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html, which has a complete example.
Generic Function, cg package
Arguments: touch-point
Returns an integer that denotes the particular input device. If the machine has multiple touch input devices, then this indicates which one is being touched.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
Designed for additional information. This is reserved for future use, and currently will always be nil.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
If known by the input device, the height of the contact area for this finger. Otherwise nil.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
A unique integer for each finger that's currently on the screen. Successive calls to touch-event will use the same ID for what is believed to be the same finger as long as it remains in contact with the screen.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
A boolean value that is true if this touch-point is in range. Microsoft says "This flag is used to enable touch hover support on compatible hardware. Applications that do not want support for hover can ignore this flag."
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
A boolean value that's true if the input is not coalesced (see Microsoft documentation for the meaning of coalesced),
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
A boolean value that is true if this touch-point is believed to be the palm of a hand rather than a finger. Note: in the implementor's testing this was always nil, so apparently only some devices have this capability.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
A boolean value that is true if this finger is the first one that made contact with the screen for the current gesture.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
A timestamp integer for this event, measured in milliseconds.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
A boolean value that's true if the timestamp is from the system clock, or nil if it's from the input device.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
One of the keywords :down, :up, or :move. The value will be :down on the first call to touch-event for this finger of this gesture, :up on the last call for this finger, and otherwise :move.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
If known by the input device, the width of the contact area for this finger. Otherwise nil.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
The X coordinate of the current position of this finger, measured in pixels. The value is in stream coordinates of the window, which means relative to the upper left corner of the canvas that the window is scrolling if it scrolls, and otherwise relative to the upper left corner of the window interior. See also touch-point-y.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: touch-point
The Y coordinate of the current position of this finger. See touch-point-x.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: window
Returns true if the specified window is currently in touch mode rather than gesture mode, handling calls to touch-event rather than gesture-event. All windows are in gesture mode by default, and can be put into touch mode by calling register-touch-window.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: window maximized-size maximized-position minimum-tracking-size maximum-tracking-size
This generic function is called whenever a window is about to be resized interactively. An application may add track-limits methods to its window classes to constrain the minimum and maximum sizes to which the end user may resize various windows, as well as their positions and sizes when maximized.
It may be particularly useful to limit how small a user can resize a dialog, in order to prevent some widgets from either being clipped off the right or bottom edges of the dialog or being resized too small when their right-attachment is :right or :scale or their bottom-attachment is :bottom or :scale.
window is the window that is being resized. The other four arguments specify the constrained sizes and positions. Any track-limits method should return these four position objects, modified if desired as described below, as the four returned values from track-limits (in the same order as in the parameter list). That is, the final form in the body of a track-limits methods should be:
(values
maximized-size maximized-position
minimum-tracking-size maximum-tracking-size)To constrain a window's size, a track-limits method should destructively modify these four position objects before returning them. When track-limits is entered, these four positions contain the default constraints from the operating system. These typically only limit a window from being resized too small to display the gadgets in the window's title bar.
maximized-size is a position where the x and y coordinates are the width and height that the window will have when it is maximized.
maximized-position is a position where the x and y coordinates are the position of the upper left corner of the window when it is maximized.
minimum-tracking-size is a position where the x and y coordinates indicate the minimum width and height to which the window may be resized by dragging its border. The resizing box will not be drawn smaller than this minimum, to visually indicate this constraint to the end user.
maximum-tracking-size is a position where the x and y coordinates indicate the maximum width and height to which the window may be resized by dragging its border. The resizing box will not be drawn larger than this maximum, to visually indicate this constraint to the end user.
track-limits is also called when resizing a window programmatically with (setf exterior) or resize-window. It is not called when a window is created, however, even though the OS defaults still apply at that time. So if an application needs to create a window that is larger than the OS default maximum (which is approximately the size of the screen), then the application should create the window in shrunk state, then resize it as desired, and then show it.
(in-package :cg-user)
;; Make a custom window subclass to test.
(defclass my-frame-window (frame-window)
;; Add a slot for remembering the window's original width.
((original-width :initform nil)))
;; Add a track-limits method to constrain interactive resizing.
(defmethod track-limits ((window my-frame-window)
maximized-size maximized-position
minimum-tracking-size
maximum-tracking-size)
;; Call the default method to let it constrain the minimum
;; tracking size of the window as usual.
(multiple-value-setq (maximized-size maximized-position
minimum-tracking-size
maximum-tracking-size)
(call-next-method))
;; Constrain the maximum tracking size to the
;; window's original width
;; and an arbitrary height of 400.
(let* ((max-width (slot-value window 'original-width)))
;; The first time that this is called, save the
;; window's current width as the maximum width
;; to use from now on.
(unless max-width
(setq max-width
(setf (slot-value window 'original-width)
(exterior-width window))))
;; Destructively modify the maximum tracking
;; width to be returned.
(setf (position-x maximum-tracking-size) max-width)
(setf (position-y maximum-tracking-size) 400))
;; Specify that when the window is maximized that it should
;; reach only to within 50 pixels of the edges of the screen.
;; Note that this size will be overridden by the more
;; restrictive maximum tracking size above, so you may
;; want to comment out the preceding section to demonstrate
;; this maximized size.
(setf (position-x maximized-position) 50)
(setf (position-y maximized-position) 50)
(setf (position-x maximized-size)
(- (interior-width (screen *system*)) 100))
(setf (position-y maximized-size)
(- (interior-height (screen *system*)) 100))
;; Return all four of the position arguments to the caller.
(values maximized-size maximized-position
minimum-tracking-size maximum-tracking-size))
;; Make a sample window to test the above track-limits method.
;; Resize and and maximize the window interactively to
;; see the constraints.
(make-window :my-frame-1
:device 'my-frame-window
:exterior (make-box 100 100 400 400)
:title "Track-limits test")Generic Function, cg package
Arguments: window
Returns (or sets with setf) whether the "empty" areas of a character will be left as they were when they are drawn. If nil (which is the default), then drawing a character on the window will also draw the window's background color to fill the parts of the character cell that are not drawn in the foreground color to form the character. If true, then these empty areas will be left alone, so that any content that was previously drawn on the window will show through the characters.
Note: in earlier versions of the documentation, this function was documented to work with dashed lines as well as characters. That was incorrect. This function does not work with dashed lines.
The value is important for functions like draw-string-in-box.
Generic Function, cg package
Argumentstray-item:
Returns the handle (an integer) of the icon that is currently being used for the specified tray-item, or nil for a default icon. The initial value is nil, and so an application would typically specify a custom icon to use before adding the tray-item to the system tray with add-tray-item. The icon may be changed at any time, regardless of whether the tray-item is currently in the tray.
The icon to display may be specified by passing an icon handle as the :icon initarg value to make-instance when creating the tray-item, or anytime later by passing the icon handle to (setf tray-item-icon).
The icon handle may be obtained by calling either extract-icon-from-file or create-icon-handle. Using extract-icon-from-file would require shipping the icon file from which it is extracted with the application. See cg-icons.html for an example of creating an icon within Lisp with create-icon-handle. One of the built-in icons such as error-icon could also be used, though this would not identify your application.
A value of nil (the default) causes the standard icon whose handle is the value of question-icon to be displayed.
A value of zero will display a blank area where the icon image would normally appear. A tray-item's icon could therefore be made to flash on and off by using a timer to switch the tray-item-icon between an icon handle and zero.
tray-item must be an instance of the tray-item class, as created with make-instance. See the description of the tray-item class for an example.
Generic Function, cg package
Arguments: tray-item window message
This generic function is called whenever a mouse event occurs over the icon for a tray-item in the system tray. It is not useful for an application to call this function, but an application may define tray-item-message methods to handle mouse events on its tray-items in some arbitrary way. The default method that specializes on tray-item and basic-pane does nothing.
tray-item will be the tray-item whose icon was under the mouse cursor when the mouse event occurred. An application would typically define and use a subclass of the built-in tray-item class so that it can specialize a tray-item-message method on that subclass.
window will be the window that was specified in the most recent call to add-tray-item for this tray-item. This is the window that receives the messages for this tray-item, and therefore tray-item-message will be called in the creation-process of that window.
message will be the value of one of the message constants mouse-moved, mouse-left-down, mouse-left-up, mouse-double-click, mouse-middle-down, mouse-middle-up, mouse-right-down, or mouse-right-up.
Here is a problem on Windows that we apparently cannot avoid: If your tray-item-message method calls pop-up-menu when handling a down click such as mouse-right-down, and the tray item's associated window was the selected window before the click was done, then the call to pop-up-menu returns immediately without letting the user choose a menu-item. Therefore, if the associated window is a visible window (which therefore might be selected), you should pop up menus only on up clicks such as mouse-right-up.
See the description of the tray-item class for an example.
Generic Function, cg package
Argumentstray-item:
Returns the string that is used for the tooltip that appears when the user pauses the mouse over the tray-item-icon for the specified tray-item, or else nil when no tooltip is displayed. The initial value is nil.
The value to use may be specified by passing it as the :tooltip initarg value to make-instance when creating the tray-item, or anytime later by passing the value to (setf tray-item-tooltip).
A tray icon tooltip string may be at most 63 characters long. An error is signaled if a longer string is specified.
tray-item must be an instance of the tray-item class, as created with make-instance.
See the description of the tray-item class for an example.
Generic Function, cg package
Arguments: window count x y dx-down dy-down dx-prev dy-prev spread-diff spread-factor first last
This generic function is called frequently while any fingers are in contact with a touchscreen on a two-stroke-mixin window (even while no fingers are moving). An application can provide methods on this generic function to handle certain kinds of gestures as they are being done. See the two-stroke-mixin class for more information.
A two-stroke-dragging method should return true if it handled the gesture, to override any default behavior. Default behavior would depend on what Microsoft does when a touch-event returns nil.
window is the two-stroke-mixin window where the gesture is being done.
count is an integer from 1 to 10 (inclusive) for the number of fingers that are currently in contact with the screen.
x and y are the integer coordinates of the current position of the first finger that made contact with the screen.
dx-down and dy-down are integers for the distance in pixels from the first finger's initial position to its current position. These coordinates would typically be used for smooth scrolling during the drag. Note that no "inertia" effect is provided for ending scrolling gradually after all fingers have left the screen; it is provided (by Microsoft) only with the gesture-event API.
dx-prev and dy-prev are integers for the distance in pixels from the first finger's position at the time of the previous call to two-stroke-dragging to its current position.
spread-diff will be nil except when two fingers are down, when it will be an integer for the number of pixels farther apart that the two fingers are than they were initially. This value and/or spread-factor would typically be used for smooth zooming during the drag.
spread-factor will be nil except when two fingers are down, when it will be a real number for the current distance between the two fingers divided by the initial distance between them.
first will be true when this is the first call to two-stroke-dragging for the current gesture, and otherwise will be nil. This is when the first finger has just made contact with the screen. If you maintain any state during the gesture that isn't provided by calls to two-stroke-dragging, you could initialize that state at this time.
last will be true when this is the last call to two-stroke-dragging for the current gesture, and otherwise will be nil. This is when the first finger that made contact for this gesture has just left the screen. If other fingers remain on the screen (and are possibly dragged farther), no futher calls to two-stroke-dragging will be made for this gesture (though two-stroke-gesture will be called only after all fingers have left the screen). If you need to finalize the continuous handling of this gesture using information that is passed here but not to two-stroke-gesture, you could do that at this time.
Generic Function, cg package
Arguments: window count gesture
This generic function is called whenever all fingers are removed from the screen after a gesture on a two-stroke-mixin window. An application can provide methods on this generic function to handle certain kinds of gestures. See the two-stroke-mixin class for more information.
A two-stroke-gesture method should return true if it handled the gesture, to override any default behavior. Returning will allow default behavior, which for a tap will call mouse-left-down and for a hold will call mouse-right-down. Other default behavior would depend on what Microsoft does when touch-event returns nil.
window will be the two-stroke-mixin window where the gesture was done.
count will be an integer from 1 to 10 (inclusive) for the maximum number of fingers that were in contact with the screen simultaneously during the gesture.
gesture will be a keyword symbol for the particular gesture that was interpreted from the many finger coordinates that were passed at a lower level to a touch-event method. Here are the possible keywords that may get passed, with their meanings:
:tap - the user did not drag appreciably, and released all fingers within two-stroke-hold-time milliseconds.
:hold - the user did not drag appreciably, and held one or more fingers down longer than two-stroke-hold-time milliseconds.
:pinch - the maximum finger count is 2, and the two fingers were moved closer to each other during the gesture by a certain threshold or more.
:spread - the maximum finger count is 2, and the two fingers were moved farther from each other during the gesture by a certain threshold or more.
:left, :up, :right, or :down - the user dragged in one of these orthogonal directions.
:left-up, :left-right, :left-down, :up-left, :up-down, :up-right, :right-up, :right-left, :right-down, :down-right, :down-up, or :down-left - the user dragged in the direction that's mentioned first in the keyword and then (with fingers still in contact with the screen) dragged in the second direction. A curved motion will still be interpreted as two directions as long as the path ventures sufficiently to one side of the line between the starting and ending positions, and where both vertical and horizontal differences between the starting and ending positions are also sufficient.
While up to ten fingers are tracked, a dragging gesture will be interpreted only from the path of the first finger that made contact with the screen. Gestures other than those mentioned above will be interpreted as the one that most closely resembles the gesture that was done.
Generic Function, cg package
Arguments: window
window must be a window of a class that includes two-stroke-mixin. This property of a two-stroke-mixin window is the number of milliseconds that distinguishes a hold gesture from a tap gesture. It can be specified by a :two-stroke-hold-time initarg to make-window, or later by calling (setf two-stroke-hold-time).
The value should be a positive integer, and it defaults to 300. If the user holds one or more fingers without dragging for longer than this time, then the gesture is interpreted as a hold, whereas less time is a tap.
Generic Function, cg package
Arguments: combo-box
Returns the value of the typable property of the argument. This property of combo-boxes determines whether users must select values from the drop-down list (value nil) or whether they may type in a new value directly (value t). typable is a property of the combo-box and the combo-box-column-mixin classes.
For combo-box controls, the typable property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :typable initarg of make-instance. It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application. This restriction does not apply to combo-box-column-mixin columns of grid-widgets.
Generic Function, cg package
Arguments: multi-picture-button
Returns a list of the names of a multi-picture-button's buttons that are present but not currently usable. The value may be set at creation time by passing the unavailable-buttons initarg, or any time later by calling (setf unavailable-buttons). The argument multi-picture-button must be a multi-picture-button.
The value should be a list of symbols, where each symbol is the name of one of the button-infos in the range of multi-picture-button. The default value is nil.
This property is useful for temporarily disallowing the use of one or more buttons, while leaving them present in their usual positions for context.
An alternative is the hidden-buttons property, which completely removes buttons from view.
Generic Function, cg package
Arguments: unavailable-color-interface
Returns or sets with setf the value of the unavailable-color-mapper property of the argument. This property determines the differing appearance of an unavailable (unclickable) button. The value is an association list (alist) grouping certain color names in the widget's pixmap with alternate color names. Unavailable widgets use the alternate color scheme.
unavailable-color-mapper is a property of the multi-picture-button, picture-button, and static-picture classes.
Generic Function, cg package
Arguments: cursor &key close-handle
This function removes cursor from the list of stored mouse cursors, though there is probably no need to do that. See cache-cursor.
Generic Function, cg package
Arguments: class-or-class-name
This function may be used to clear a cache that is used by class-grid widgets and object-editor dialogs if programmatic changes may have made the cache out-of-date.
class-grids and object-editors cache a list of the instances that they display, along with the pretty names that are used to present the instances to the end user. This is done to avoid consing the pretty names when the instances are sorted by the pretty names or presented in menus and so on. As long as the instances are modified only by the end user via class-grids and object-editors, the cached pretty names are kept up-to-date. But if an application uses some other means to modify the instances so that their pretty names may no longer be up-to-date, then it can call this function to clear the cache for one or all classes. For example, if the primary-name-slot of the "person" class is last-name, and the application programmatically changes the value of that slot for one or more person instances, then it should call this function on the person class.
class-or-class-name may be either a class object or the name of a class. It can also be the keyword :all to clear the entire cache of pretty names for all classes.
Generic Function, cg package
Arguments: pixmap &key close-handle
Removes pixmap from the set of cached pixmaps. Cached-pixmaps can be located by using find-pixmap, which is handy to prevent making redundant instances of a pixmap. Also closes pixmap's pixmap handle if it has one (this is to free up operating system pixmap resources on the assumption that you are no longer using this pixmap, though in fact you could still use it).
Generic Function, cg package
Arguments: menu-item
This menu-item property is implemented only on the Windows platform.
Returns the pixmap, if there is one, that was specified to be displayed on the left side of the menu-item when the menu-item is not checked (meaning when it's selected property is nil). If no such pixmap was specified, then nil is returned.
The pixmap can be specified by passing an unchecked-pixmap initarg when calling make-instance to create the menu-item. The value should be either a pixmap or nil, and the default is nil. If the menu-item's checkable property is nil, then this pixmap will be displayed all of the time. This pixmap on the left side is distinct from the one that can be displayed instead of string by using a pixmap for the title property.
See also checked-pixmap.
Generic Function, cg package
Arguments: text-edit-pane
The function returns t if all of the selected range of text-edit-pane is underlined, nil if it is all not underlined, and :some if there is a mix.
The setf function turns underlining on or off in the selected range of text-edit-pane. value is either nil to turn it off or true to turn it on.
text-edit-pane must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).
See cg-rich-text.html for information about rich text editing in Common Graphics.
Generic Function, cg package
Arguments: window
This function has an effect only in Windows desktop mode. In CG/JS mode, undo and redo in a text-editing widget can be done only by typing Control+Z and Control+Y (or Command+Z and Command+Y on a Mac). That lets the web browser perform its built-in behavior, which cannot be invoked programmatically. See also send-undo-keystrokes-to-server.
Modifies window so that it is in the state that it was in just before the most recent edit was made by the user. The window may be (1) a standalone text-edit-pane, (2) the widget-window of a multi-line-editable-text, editable-text, or a typable combo-box widget (as returned by calling window on the widget), or (3) a form window in an IDE project. In the IDE, the Edit | Undo command calls this function on the selected window.
When the window is a text-edit-pane (on the Windows platform), multiple calls to this function with no intervening text editing will undo successive edits, and redo-command must be used to redo each edit that was undone. For all other windows, a second call to this function with no intervening editing will redo the single undo that can be done.
In a form window, this will undo the most recent change to a property of the form itself, or undo the creation or deletion of a widget on the form. In other windows it affects text editing.
Generic Function, cg package
Arguments: dropping-outline &optional no-set-focus-p
It probably wouldn't be nice for an application to call this function to programmatically hide the dropping pane of a dropping-outline that the user is looking at. But it might be useful to add an :after method for side effects, such as moving the keyboard focus to some other widget.
Function, cg package
Arguments: combo-box
Undrops (closes) combo-box programmatically.
Generic Function, cg package
Arguments: grid-section
Returns (or sets with setf) whether resizing a subsection of grid-section will cause all of its subsections to become the same new size as the explicitly resized subsection.
When the Control key is held down as the resizing is initiated, the uniform-resizing effect will be the opposite of the uniform-resizing setting of the grid-section.
uniform-resizing is a property of the grid-section, grid-column-section, and grid-row-section classes.
Generic Function, cg package
Arguments: picture-button-or-multi-picture-button
Returns whether a picture-button will automatically unpress itself just after the user has pressed it interactively, or whether a multi-picture-button will automatically unpress any of its buttons just after that button is pressed interactively. The default value is nil, which means that a pressed button will stay pressed until the user unpresses it explicitly (or presses another button within a multi-picture-button when its multiple-selections property is nil). The setf of this function may be called to set the value of this property, or it may be specified when creating the widget by passing the unpress-automatically initarg to make-instance.
If the value of this property is true, then when the user presses a button interactively, the button will be unpressed automatically just after the widget's on-change function (if any) has run. The unpressing of the button is therefore a visual indication of when the button has completed its action. The button is unpressed internally by calling initialize-value, and so the on-change function will not be called again as a result of the unpressing.
This property affects only interactive button-pressing, and does not affect pressing buttons programmatically by calling (setf value). A button may be pressed interactively either by clicking it or by pressing the spacebar when the button has the keyboard focus (for a multi-picture-button, the latter requires the draw-focus property to be true).
Setting this property to true is essentially equivalent to returning (not new-value) from the on-change function, which would return nil to reject the new value when a button is pressed down, but return true when all buttons are unpressed. We had suggested that return value in earlier releases, but that technique was rather obscure.
For a multi-picture-button, setting this property to true when the multiple-selections property is also true is probably not useful, since there would be no way for the user to press multiple buttons down interactively (though that would still be possible by calling (setf value).)
;; In the following example, my-multi-picture-button
;; is assumed to be the widget object (rather than,
;; say, the widget name). To test this, you could
;; use the Tools | Get Component command, then click on a
;; multi-picture-button to return it, and then evaluate:
;; (setf my-multi-picture-button *)
(setf (unpress-automatically my-multi-picture-button) t)Generic Function, cg package
Arguments: window
Causes the specified window to receive gesture messages thereafter, rather than touch messages. This is the default for any window, and so this function is needed only to return a window to gesture mode after placing it into touch mode by calling register-touch-window.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
Generic Function, cg package
Arguments: dialog-item
Use of this function is deprecated. Common Graphics now always internally calls subclass-widget on all widgets for more consistent message handling. Since Common Graphics depends on Microsoft controls being in this subclassed state, unsubclass-widget has been changed to simply do nothing so that any leftover calls to it in application code will have no effect.
Generic Function, cg package
Arguments: widget
Returns the up-down-control control associated with the control specific by the argument widget, if there is one. Returns nil if there is no associated up-down control. Up-down controls are usually associated with editable-text controls but the argument can be any type of control.
If an up-down control (rather than nil) is returned, applying buddy-widget to that up-down control should return widget.
Function, cg package
Arguments:
This function may be used to update any class-grid widgets and object-editor dialogs that exist if programmatic changes to the instances that they are displaying may have made the displayed values out-of-date.
If an interface contains a set of class-grids and object-editors, and the instances that they are editing are modified only by the end user through that interface, then everything should stay up to date. But if the application programmatically changes instances that might be currently displayed, then it can call this function to update any class-grids and object-editors that might be displaying the instances.
Function, cg package
Arguments: chart-or-plot &key update-now
This function recomputes the value range of a chart-or-plot and invalidates so that it is redrawn with the new value range. The return value is undefined.
Normally this would be needed only if existing values in a chart or plot have been changed to smaller values that would fit into a smaller range. Other modifications to the chart should update the chart automatically, including when a new value lies outside the current value range, but this special case would be inefficient to check for.
This function would have no effect if you have specified true values for both the range-bottom and range-top properties of the value axis, since the value range is never autocomputed in that case.
See chart-widget, plot-widget, and also cg-chart-widget.html.
Generic Function, cg package
Arguments: dialog new-dialog-items
Updates dialog to contain new-dialog-items, which must be a list of dialog-items. new-dialog-items must not be the destructively modified list returned by dialog-items applied to dialog because that list is used to compute screen changes. (Make a copy of that list, e.g. with copy-list, if necessary.)
Generic Function, cg package
Arguments: drawable
Causes drawable (an instance of the drawable class) to be redisplayed, either by calling the on-redisplay function or by causing the image in the bitmap-stream associated with drawable to be displayed.
An application may call update-drawable on a drawable that uses an on-redisplay function that draws its drawing based on parameters that may change over time. This forces the on-redisplay function to be called in order to draw the current version of its drawing when the control may not otherwise need to be redrawn.
If done in rapid succession, this can produce animation effects, especially if the use-bitmap-stream property is currently turned on in order to eliminate the flashing that is produced when erasing and redrawing directly on the visible window.
Function, cg package
Arguments: lamp
Causes the specified lamp widget to be redisplayed, including in any grid-widget cells that display it. The return value is undefined.
Updating is usually not needed since replacing lamp properties will update the lamp automatically. But if a lamp's value is an array and an application modifies the array's values directly, the lamp widget does not realize this (or so does not redispaly automatically). In that case a call to update-lamp is needed to ensure that the lamp is redisplayed to reflect the new values in the array.
It also works to set the value property of the lamp widget to be the array that is already the value of that property. This was the required technique before update-lamp was added.
Generic Function, cg package
Arguments: menu new-items
This function allows items to be added to or removed from menu. new-items should be a list of menu items, and it will become the list of items displayed in the menu. Note that new-items must not be the destructively modified item list of menu (returned by menu-items) because the two lists are compared to compute screen changes. You may copy that list (with say copy-list) to provide a starting point for the new-items list.
Note that a menu-item should only be added to one menu. If a similar menu-item must appear in more than one menu, create copies (by calling (make-instance 'menu-item) with identical arguments or calling copy-menu-item) as necessary. See the description of the menu-item class.
Generic Function, cg package
Arguments: widget
Use of this function is deprecated. It is no longer needed because :after methods on the button-info property setters perform the update automatically. Calls to this function should be removed from user code. This function will likely be removed in a later release.
Needlessly recomputes the layout of buttons on widget, which should be a multi-picture-button, and redisplays it.
Generic Function, cg package
Arguments: drawable
Returns (or sets with setf) whether a drawable will be redrawn in its entirety whenever it is resized. This property is true by default.
If this property is false and use-bitmap-stream is true, then the upper left portion of the drawable's visible window may not be invalidated after a resize on the assumption that the part of the drawing which already appears there is still current. If use-bitmap-stream is true, then the window will simply be refreshed from the bitmap-stream as usual.
If this property is true, then update-drawable is always called to completely redraw the drawing. It is true by default.
Generic Function, cg package
Arguments: window
This generic function is called internally when a window is created and later whenever the interior size of the window changes or its page size changes. An application should not call this function. If an application defines a custom scrolling scheme, then it likely will need to define an update-scroll-bars-for-new-window-size method that calls set-scroll-range to set the scroll-bars of the window as needed for the new window size.
See horizontal-scroll-bar and vertical-scroll-bar.
Function, cg package
Arguments: filename
Causes all picture-button and static-picture widgets that use filename as the source of their displayed image to re-read the image from the file. Normally the image is cached in Lisp, so this function is useful if you have edited the image file and want to update all of the widgets that use that file's image.
Function, cg package
Arguments: window
Calling this function causes any pending redisplay of window to be performed sooner than it would be by default. If window was created in the process that is calling update-window, then the redisplay will be immediate, and is guaranteed to be completed by the time that the call to update-window returns. If the window was created in some other thread, than the redisplay may happen sooner than it would be otherwise, though it will still happen asynchronously.
Normally the operating system invokes a window's redisplay-window method only after the process that created the window finishes handling other messages. This design avoids redundant redrawing of windows, which can slow down an application and produce annoying flashing effects. But if this design excessively delays the redrawing of a window, update-window may be called at any time to ensure that the window is brought up-to-date at that time.
See also redisplay-window, invalidate, and with-delayed-redraw.
Starting with Allegro CL release 6.1, if the window was created in a process other than the process that is calling update-window, the window will not be updated immediately as it was in prior releases. The window will instead be updated only when the window's process (returned by creation-process applied to the window) runs again as usual and after the process has handled any messages that were already queued when update-window was called. This may, however, still update the window sooner than if update-window were not called, because a message is posted to the window telling it to update itself immediately when it gets to that message.
Before this change, a process calling update-window on a window in another process would always block until the other process performed further message handling and redisplayed the window. However, this waiting introduced the potential for deadlocks. With the change, deadlocks are avoided at the cost of perhaps some delay to window updating.
See cg-drawing.html for a discussion of the uses of redisplay-window, invalidate, and update-window.
Function, cg package
Arguments: object
Returns a string with the print-name of object uppercased.
Generic Function, cg package
Arguments: window-or-screen
Returns the interior height of a window or the screen that is available for application use.
window-or-screen should be either a window or the screen.
When the screen, the returned value will be the value returned by virtual-screen-height when there are multiple monitors, and otherwise it will be the interior-height of the screen (which is the height inside the system taskbar if it takes up space on the top or bottom).
When a window, the returned value is the page-height of the window when the vertical scrollbar is enabled, and otherwise it is the interior-height of the window.
Generic Function, cg package
Arguments: window-or-screen
Returns the leftmost coordinate inside a window or the screen that is available for application use.
window-or-screen should be either a window or the screen.
When the screen, the returned value will be the value returned by virtual-screen-left when there are multiple monitors, and otherwise it will be the left of the interior of the screen (which is zero unless the system taskbar takes up space at the left of the screen).
When a window, the returned value is zero.
Generic Function, cg package
Arguments: window-or-screen
Returns the topmost coordinate inside a window or the screen that is available for application use.
window-or-screen should be either a window or the screen.
When the screen, the returned value will be the value returned by virtual-screen-top when there are multiple monitors, and otherwise it will be the top of the interior of the screen (which is zero unless the system taskbar takes up space at the top of the screen).
When a window, the returned value is zero.
Generic Function, cg package
Arguments: window-or-screen
Returns the interior width of a window or the screen that is available for application use.
window-or-screen should be either a window or the screen.
When the screen, the returned value will be the value returned by virtual-screen-width when there are multiple monitors, and otherwise it will be the interior-width of the screen (which is the width inside the system taskbar if it takes up space on the left and right sides).
When a window, the returned value is the page-width of the window when the horizontal scrollbar is enabled, and otherwise it is the interior-width of the window.
Generic Function, cg package
Arguments: drawable
Returns (or sets with setf) whether a drawable uses a bitmap-stream on which output is drawn before being copied to the visible window of the control. To use a bitmap-stream, an application need only turn this property on, either by passing the :use-bitmap-stream initarg as true when creating the drawable, or calling (setf use-bitmap-stream) later. The drawable will automatically create a bitmap-stream of the proper size as needed.
If a drawable uses a bitmap-stream, it is returned by the bitmap-stream function. The function drawable-stream applied to a drawable returns the bitmap-stream if there is one.
A drawable will work just fine without a bitmap-stream, but a bitmap-stream may be used for various special reasons. Here are the steps involved for a few of these reasons after turning the use-bitmap-stream property on:
To store what was drawn once and recopy it quickly to the window when needed (as with a bitmap-pane). When you do this, you should:
Do not give the drawable an on-redisplay function. (An on-redisplay function should redraw the image when necessary. However, the bitmap-stream acts as a backing store, redisplaying automatically when necessary.)
Retrieve the bitmap-stream by calling bitmap-stream on the drawable.
Call clear-page on the bitmap-stream to erase any old drawing.
Draw something on the bitmap-stream.
Call invalidate on the drawable to display the drawing on the visible window.
From now on, whenever the drawable is uncovered, its drawing will be refreshed from the bitmap-stream.
To switch quickly from one ad hoc drawing to another.
Simply repeat the above procedure a number of times when needed. This avoids the flashing that would be seen by erasing and drawing directly on the visible window.
Animation effects, or changing the drawing at scheduled times.
Supply an on-redisplay function along with use-bitmap-stream.
Write the on-redisplay function so that it reads parameters that change, causing it to draw its drawing differently.
When it is time to go to the next version of the drawing, call update-drawable on the drawable. This will cause the on-redisplay function to be called to draw the new version on the bitmap-stream and then copy the drawing quickly to the window.
If the parameters are changed quickly, calling update-drawable each time, an animation effect can be achieved.
If use-bitmap-stream is toggled on and off, a new bitmap-stream is created only if the most recent one is not large enough either horizontally or vertically. So toggling this property should not be inefficient.
The bitmap-stream is also grown as needed automatically when the page size of the drawable is increased. This includes the case where (1) the scrollbar in either direction is not enabled, (2) no explicit page size has been given in that direction, and (3) the drawable itself is sized larger in that direction; in this case the default page size follows the interior size of the drawable, and the bitmap-stream is made larger as needed.
Generic Function, cg package
Arguments: configuration
This configuration property determines whether the built-in cg-timer will run all the time, never, or whenever the mouse cursor is over a Common Graphics window. The default is nil, meaning never.
In addition to the general timers facility (see cg-timers.html), Common Graphics by default automatically starts up one particular timer instance called the cg-timer. This timer is used internally by both Common Graphics and the IDE, and applications can use it as well (see cg-timer and handle-cg-timer). It runs both in the IDE and in standalone applications.
Here are the possible values of this property and things to consider for each value:
:under-mouse: this option indicates that the cg-timer will run whenever any Common Graphics window is under the mouse cursor. (This includes all IDE windows, but not the Console window.) A small inconvenience of this option in the IDE is that the red "Tracing" and "Sampling" reminders that appear in the upper right corner of the IDE will be updated only when the mouse cursor is over a Lisp window. For these flags to update at all times, change use-cg-timer to t.
t: the cg-timer will run at all times, even when the IDE or standalone application is shrunk or buried by other applications. Note that this option potentially could interfere with time-critical applications. You probably want to use this option only if you have added a custom handle-cg-timer method to some window that needs to run even when the mouse is not over any Lisp windows, though using a custom timer instance rather than the cg-timer may allow more flexible control in this case.
nil: the cg-timer will never run. This is the default. The main drawback with this option is that no mouse-out message will be generated by Common Graphics when the mouse moves from a Common Graphics window directly onto another application or the desktop. (The mouse-out message will still be generated once the mouse moves onto another Common Graphics window though.) For a standalone application that does not depend on mouse-out messages when the mouse is not over the application, you may want to use this option simply to eliminate unneeded message processing. Prior to multithreaded Common Graphics, the saving was usually not noticeable, but in a multithreading environment, it can be significant, which is why the default was changed to nil.
use-cg-timer is a property of the configuration class.
Generic Function, cg package
Arguments: multi-picture-button
Returns the value of the use-default-tooltips property of the argument multi-picture-button. Each button on a multi-picture-button can have its own tooltip. The tooltip can be specified as the tooltip property of the button-info instances that make up the multi-picture-button.
This property controls whether the tooltip string should be taken from the button-info name if the tooltip property is nil (if the tooltip property is true, it will be used regardless of the value of this property).
If the value is nil, buttons on the multi-picture-button (button-info instances) that do not have a true tooltip property have no tooltip. If the value is t, the original name of each button is used as its tooltip unless an explicit tooltip value is specified for the button (if one is, use it of course).
use-default-tooltips is a property of the multi-picture-button class.
Generic Function, cg package
Arguments: combo-box-column-mixin
Returns (or sets with setf) whether the drop-down that is shown by a combo-box-column-mixin
Generic Function, cg package
Arguments: cg-congfiguration
This Common Graphics user option allows using special mouse clicks to copy or move Lisp forms in a lisp-edit-pane (such as in the IDE's code editor).
cg-configuration should be a configuration object such as returned by configuration (typically (configuration *system*)).
When enabled, a control-left-click will copy the form that's at the click position to the text cursor position, whereas a shift-control-left-click will move the form instead. If any text is currently selected, it will be replaced by the copied or moved text.
To copy or move a form, click just before the opening parenthesis of the form or just after the closing parenthesis if there is no opening parenthesis at the same character position:
;; In this case:
(foo) (bar)(baz)
;; clicking on the opening or closing parenthesis of (foo) copies (foo)
;; but you can only click on the opening parenthesis of (bar). Clicking on
;; the closing parenthesis of (bar) copies (baz) since that position is
;; also the opening parenthesis of (baz).To copy a string, click just before the opening double-quote character. Otherwise the word that is at or near the clicked position will be copied; this may be a symbol, or simply a set of characters that could be read as a symbol.
This feature may be most useful when you are typing in new code and are about to re-type something that is visible elsewhere in the editor buffer. In this case you can simply click on the expression to copy it to the point where you are entering code, and then modify it as needed.
This option is off by default, but can be enabled with this form:
(setf (use-mouse-clicks-to-copy-lisp-forms (configuration *system*))
t)Generic Function, cg package
Arguments: ocx-widget
Applies to the Windows platform only.
Returns the value of the use-native-size property of an ocx-widget. This value is normally specified with the :use-native-size keyword argument to def-cg-ocx-control; refer to that macro for more information.
It is possible to change the value of this property of an existing widget by calling (setf use-native-size), but we expect that this is not useful.
Generic Function, cg package
Arguments: configuration
Returns (or sets with setf) whether open-pixmap-handle will actually create a pixmap handle in configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).
The value t means that open-pixmap-handle will in fact create a pixmap handle when it should as documented under open-pixmap-handle. If set to nil, then open-pixmap-handle will never create a pixmap handle. use-pixmap-handles is a property of the configuration class.
Generic Function, cg package
Arguments: combo-box-column-mixin
This combo-box-column-mixin option has been deprecated. The default value of nil should always be used. Setting this option to true can lead to problems with some combinations of other options, and so this option should not have been provided. On the Windows platform, this option tells a Microsoft combo-box widget to show its drop-down pane even though the combo-box itself is hidden, which the OS does not expect.
Returns true or nil to indicate whether the argument, which must be an instance of grid-column and of the mixin class combo-box-column-mixin, uses a standard combo-box control to show its drop-down list of choices, rather than using whatever simulation of a combo-box control is used by default (the default is nil).
This provides a choice for alternative styles for grid-widget combo-box cells, and an application may use whichever one is more suitable for it. This property may be set either by calling the setf of this function or by passing the :use-real-combo-box initarg to make-instance.
In the current Windows implementation, the default value of nil causes a pop-up menu to be used. The menu will always be as wide as needed in order to display the complete string for each choice. A value of true causes a Windows combo-box to be used instead. The combo-box will always be just as wide as the grid-column is, and therefore may clip some of the choice strings. The combo-box may be closed by pressing alt-uparrow, as with a standalone combo-box control. Alt-downarrow may be used to open either type, as an alternative to pressing either the spacebar or the return key. The two styles have different borders.
Function, cg package
Arguments:
This function was specific to GTK, which is no longer supported, and so this function is no longer needed.
Generic Function, cg package
Arguments: stream
This function is called when a user of a program makes a closing gesture. Returns true if closing was successful, nil if not (for example if the user canceled the action). stream should be a cg-stream.
An application can add user-close methods that consider whether to grant the user's request to close the window, perhaps by popping up a confirmation dialog. If it is decided that the window should in fact be closed, then the user-close method should call the function close to actually close it.
If an application might get run in CG/JS mode, then any user-close method that prompts the user should first call web-browser-has-disconnected and not do the prompt if it returns true. Otherwise it could hang waiting on the disconnected browser to reply, preventing Lisp from unwinding and exiting.
See also device-close, which is also called when a window is closed, even programmatically.
The default user-close method on basic-pane simply calls close and returns t, unless the close-button property of the window is nil (meaning that there is no close button in the window's title-bar if it has one), in which case it does nothing and returns nil.
There is also a built-in :around method on basic-pane that checks to see if the window is currently being invoked modally by a call to pop-up-modal-dialog. If so, then this method calls the cancel-button's on-change function if there is a cancel-button on the window, and otherwise calls flag-modal-completion. If the window is not currently being invoked modally, then this method simply calls the next method. This :around method generally should not be overridden.
See also os-exit-request, which lets the user confirm an attempted shutdown of the entire operating system, and confirm-web-browser-exit, which in web browser mode lets the user confirm the closing of the browser tab of the application.
Generic Function, cg package
Arguments: printer
Returns whether the application (rather than the printer driver) should collate printed copies. If this printer stream property is turned on, it indicates that the user has requested on the print job dialog that the printed output be collated, and also that the printer driver is not capable of doing the collating internally, and so it is obligated to print pages in a collated order explicitly.
Whether to collate may be specified programmatically by passing the :collate-p initarg to open-stream when creating the printer stream, or may be specified by the end user on the print job dialog that appears by default when calling open-stream to create a printer stream. The values of the driver-collate-p and user-collate-p properties will then indicate whether the application or the printer driver should handle the collating, if any.
user-collate-p is a property of the printer class.
Generic Function, cg package
Arguments: printer
Returns the number of copies that the application (rather than the printer driver) should print. If this printer stream property is greater than 1, it indicates that the user has requested on the print job dialog that multiple copies be printed, and furthermore that the printer driver does NOT know how to print the multiple copies itself, and so the application is obligated to explicitly print this number of copies of whatever output is currently being printed.
The number of copies to print may be specified programmatically by passing the :copies initarg to open-stream when creating the printer stream, or may be specified by the end user on the print job dialog that appears by default when calling open-stream to create a printer stream. The values of the driver-copies and user-copies properties will then indicate whether the application or the printer driver should handle printing the multiple copies, if any.
user-copies is a property of the printer class. Note: this generic function is not setf'able.
Generic Function, cg package
Arguments: object
Returns whether the user is able to interactively cycle through the set of pixmaps in the pixmap-alist property of a static-picture or pixmap-column-mixint.
When the value is true, the user can select the next pixmap by clicking on the widget or grid cell, or by pressing the spacebar when the widget or grid cell has the keyboard focus.
Generic Function, cg package
Arguments: window scroll-type new-position
This function is used only when running in Windows desktop mode.
It is called by the system whenever the user makes a scrolling gesture. It should not be called directly by the program, but may be modified to customize scrolling behavior on the program's own window classes.
scroll-type is one of :left, :right, :up, :down, :thumb-continuous, :thumb-finished. The thumb values indicate a dragged scroll-box (also known as "the thumb" or "slider"), while the other values indicate single-click page or line scrolling.
new-position is either :character or :page. :character indicates that a small (line or character) scroll was requested, typically by mousing one of the arrows at the end of the scroll bar or by pressing the arrow keys on the keyboard. :page indicates that a large (page) scroll was requested, typically by mousing the body of the scroll bar or pressing the page-up or page-down keys.
An application may override the default method of this and several other generic functions in order to implement a custom scrolling scheme that scrolls by logical picture objects rather than by pixels. See the source code of the example entitled 'Scrolling by arbitrary objects rather than pixels' on the Examples tab of the Navigator dialog for a complete example. More on this point and a list of the relevant generic functions can be found on the horizontal-scroll-bar and vertical-scroll-bar pages.
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments: &key hidden child-directory-name
Returns the pathname of a directory where it is suitable to save utility files for the current user, such as option files. An application could call this function to determine the directory to save such files in.
The returned directory will be the value of *utilities-directory* if it has arbitrarily been set to a file path instead of its default value of nil. Otherwise, the directory will basically be the user's home directory, defined on Windows as the user's Documents directory. Appended to this directory will be the child-directory-name argument if it has been passed as a string (it should not contain slashes), or else the utility-file-directory of a project if the project is now running as a standalone application; though on Linux this child directory is appended only if the hidden argument is true. On Windows, and on Mac when hidden is nil, any leading "." or ".d" will first be stripped off of the child directory name, because that is a Linux convention. And on Mac when hidden is nil, the child directory will be used as a child directory of the Documents child directory of the user's home directory.
This function is provided mostly for application use, though one time that CG uses it internally is to look for a file with a name like appname-startup-options.txt (where appname is the name of the executable file) when a generated application is starting up. The application itself needs to write that file in this directory (passing hidden as true) if it has asked the user for startup options. That file can contain a single line of CG/JS command-line arguments that will be used for subsequent runs, such as -b yes to run in web browser mode. So the application might have a "Run In Web Browser" checkable menu-item, and if the user toggles it on then the app could write -b yes into this file, and the app will run in a web browser next time.
Generic Function, cg package
Arguments: project
If this project property is non-nil, then it should be a string that names a subdirectory, without any slashes in the string. In that case, the function utilities-directory will append that subdirectory to the directory that it returns when the project is running as a standalone application.
The value can be set interactively in the Utility File Directory widget on the Options tab of the Options dialog.
Function, cg package
Arguments: base-file-name &key hidden child-directory-name
Returns a file pathname where it is suitable to save the specified utility file like 'foo.txt' for the current user. This merges base-file-name with the directory that's returned by calling utilities-directory with the same hidden and child-directory-name arguments, and returns that pathname.
One exception on Linux and Mac is that if hidden is true and this is not a standalone application whose project has a utility-file-directory, then a period is prepended to base-file-name, as is customary for hidden files.
Generic Function, cg package
Arguments: window standard-object slot-name value
This generic function is called whenever a user attempts to enter a new slot value in an object-editor dialog or a class-grid widget. If it returns true then the new value is accepted, and if it returns nil then the value is rejected and the object-editor widget or the class-grid cell will continue to show the pre-edited slot value.
The default method simply returns t to allow any edit. An application could define one or more methods that override the default method to check whether the user has entered an invalid value, returning nil if so. A method could also show an error dialog explaining why the value was rejected, for example.
window will be either an object-editor dialog or the parent window that a class-grid is on. This is a suitable window to serve as the owner of an error dialog.
standard-object will be the object that is currently displayed in an object-editor dialog, or in the selected row of a class-grid widget.
slot-name will be the symbol that names the slot that is edited by the particular object-editor widget or class-grid column in which the user is currently editing a value.
value will be the newly edited value that the user is attempting to write into the slot.
Here is a simple example that allows a particular slot to contain only a string where every character is a letter. (The class does not need to be a persistent AllegroCache class, but that is typical when using an object-editor or class-grid.)
(defclass my-thing ()
((foo :accessor foo :initform "" :initarg :foo))
(:metaclass db.ac:persistent-class))
(defmethod validate-edited-slot-value
((window basic-pane)(my-thing my-thing)(slot-name (eql 'foo)) value)
(cond ((and (stringp value)
(every #'alpha-char-p value))
t)
(t (pop-up-message-dialog
window "Invalid Value"
#.(format nil "The value of the foo slot must be ~
a string that contains only letters.")
warning-icon "~OK")
nil)))Generic Function, cg package
Arguments: window &optional box erase-p
Marks window (to the operating system) as not being in need of a redisplay causing any pending repaint messages to be discarded. If box is supplied, only the region specified by box will be validated. erase-p is ignored (it allows the same arguments as passed to invalidate-window to be passed to this function).
Generic Function, cg package
Arguments: standard-object
Returns the value of the value property of the argument. The value property holds the value of a control or component. The format of the value depends on the type of component (it might be a number, a string, a boolean (t or nil), etc.) Often the value is changed by user action, usually in a dialog displayed precisely to get user input.
(setf value) may be called to change the value of a control programmatically. The appearance of the control will update to reflect the new value, just as if the user had specified the new value interactively. If the control has an on-change event handler function, and the on-change-test function of the control determines that the new value is considered to be different from the previous value, then the on-change function is called. (To change the value without invoking the on-change function, call initialize-value instead.)
For controls with a range (such as a trackbar or a combo-box), it is an error to specify a value, either initially with the :value init argument or with setf of value, outside the range.
See also fetch-control-value, which forces the operating system to update the value of a control. There are cases (discussed in the description of that generic function) where the value returned by value might be out of date.
If you call (setf value) and notice that the widget is not redrawn to display the new value as expected, the problem may be that the widget's on-change-test function regarded the new value as being equivalent to the old one, and therefore that no updating was needed. This problem can be remedied by changing the on-change-test to a function that properly returns nil for any two values that should be considered distinct. In particular, if you destructively modify the object that is the current value of a widget, and then set the value of the widget to be that same modified object, then the default on-change-test function (widget-value-equal) will return true because the new and old values are eq, and the widget's appearance will not be updated. Specifying nil as the on-change-test will avoid the problem in special cases such as this, by causing the new and old values never to be regarded as equivalent.
(setf value) takes an additional optional argument called recursive-p. This argument will be true if (setf value) is being called due to the user modifying a widget interactively, such as by typing into a text widget. An application should not pass this value as true, but it might be informative in a wrapper method.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the value-axis property of a chart-widget. The value may be set at creation time by passing the :value-axis initarg, or any time later by calling (setf value).
value-axis is an axis of a chart-widget that indicates the magnitude of the displayed data values. This property value is an instance of the value-axis class, and holds properties that determine how the axis is drawn and the range of values that it displays.
The value of this property is always a value-axis instance. If you do not pass a value-axis instance as the value of the :value-axis initarg when creating a chart-widget, then a default instance is created automatically.
If there are multiple chart objects (see chart-objects), then some of the objects may use this value axis while others use the secondary value axis that is in the value-axis-2 property.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the value-axis-2 property of a chart-widget. The value may be set at creation time by passing the :value-axis-2 initarg, or any time later by calling (setf value-axis-2).
value-axis-2 is a secondary axis of a chart-widget that indicates the magnitude of the displayed values. The value is an instance of the value-axis class, and holds properties that determine how the axis is drawn and the range of values that it displays. This axis will be drawn only when one or more of the chart objects are explicitly associated with this second axis in the chart-objects property.
The value of this property is always a value-axis instance. If you do not pass a value-axis instance as the value of the :value-axis-2 initarg when creating a chart-widget, then a default instance is created automatically.
If there are multiple chart objects (see chart-objects), then some of the objects may use this value axis while others use the primary value axis that is in the value-axis property.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: list-view-item column-name
Returns the value of the item specified by the arguments. See the descriptions of the list-view control and the list-view-item class.
Generic Function, cg package
Arguments: list-view-item
Returns the plist of the argument. value-plist is a property of the list-view-item class.
Generic Function, cg package
Arguments: line-graph-view
Returns the value of the value-spacing property of a line-graph-view. The value may be set at creation time by passing the value-spacing initarg, or any time later by calling (setf value-spacing).
The minimum spacing, measured in pixels, between successive chart items on a line-graph-view in a chart-widget. The value should be a positive integer. The default value is 12.
The actual distance will be greater if needed to prevent tic labels on the item-axis from overlapping each other. See major-label-min-spacing and major-label-wrapping.
If the fit-chart-items property of the chart-widget is true, then this value will be scaled proportionally with other sizing properties to make all data fit in view.
This property is used only when the draw-lines property is true.
See also bar-spacing.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-or-plot
Returns the value of the value-types property of a chart-or-plot. For a chart-widget, the value may be set at creation time by passing the :value-types initarg, or any time later by calling (setf value-types).
This property declares which of the possible types of values a chart-or-plot should currently draw. This can be used to filter out some types of values that would otherwise be drawn, or to view different parts of the available data at different times. It is also useful for efficiency by telling the widget not to waste time looking up particular kinds of values that have not been supplied.
The value may be any subset of the list (:value :from-value :high-value :low-value :icon-size). The default value is the entire list. See set-chart-value for the meanings of these value types.
When a chart is being drawn, it will look up only the specified types of values in the chart-items property, to find any that were added there by calls to set-chart-value. If the widget has a chart-value-returner function, then it will be called with each of the specified types of values whenever a value is not found in the chart-items property.
For a plot-widget, the value may be any subset of the list (:x :y :x-low :x-high :y-low :y-high :icon-size). The default value is the entire list. See set-plot-value for the meanings of these value types.
When a plot is being drawn, it will look up only the specified types of values in the plot-values property, to find any that were added there by calls to set-plot-value. If the widget has a plot-value-returner function, then it will be called with each of the specified types of values whenever a value is not found in the plot-values property.
See also draw-high-low-values.
See chart-widget and also cg-chart-widget.html.
Generic Function, cg package
Arguments: chart-view
Returns the value of the values-are-stacked property of a chart-view. The value may be set at creation time by passing the values-are-stacked initarg, or any time later by calling (setf values-are-stacked).
This property specifies whether the data values in a chart-view of a chart-widget are stacked to show cumulative values on the value-axis. The default value is nil.
This property is relevant only when the widget has multiple objects (see chart-objects), because otherwise there is nothing to stack.
For a bar-chart-view (when the chart-view of the chart-widget is :bar), a true value will stack the multiple bars of each chart item so that they lie end-to-end. A null value will place the bars side-by-side instead. The stacked option saves a lot of space, but can make it somewhat harder to compare the multiple chart objects. If bars are stacked and some values are above the base-value of the bar-chart-view while others are below, then all of the values that are above the base-value are stacked in one direction and all of the values that are below the base value are independently stacked in the other direction.
For a line-graph-view (when the chart-view of the chart-widget is :line), a true value will stack the data values so that the line for each chart object is relative to the lines of the chart objects below it. This is like a stacked area graph, though the areas between the lines are not filled. A null value will draw the lines independently of each other, which typically causes more crossing of the multiple lines.
For any true value other than :downward, the first object in the sequence of chart-objects is charted first, then the second object is stacked on the values of the first, and so on. For the special value :downward, the objects are stacked in the opposite order, which (when chart-orientation is :vertical) would match the direction in which the objects are listed from top to bottom in the chart's legend.
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments: font &key family face size style
Creates and returns a font which is similar to font, but differs in any of the specified components.
(vary-font font :style (cons :italic (font-style font)))creates a font like font but italic. See make-font.
Generic Function, cg package
Arguments: object
Returns a symbol indicating how text is aligned vertically in the cells of a grid-column or in a scrolling-static-text widget. The value may be set at creation time by passing the vertical-justification initarg, or any time later by calling (setf vertical-justification). The value may be :top, :center, or :bottom. The default value is :top.
For grid-widget cells, the default cell-vertical-justification method will use this grid-column property, but a custom cell-vertical-justification method may override it.
Generic Function, cg package
Arguments: grid-column
Returns the default cell-vertical-padding for the cells of a grid-column. The value may be set at creation time by passing the vertical-padding initarg, or any time later by calling (setf vertical-padding). The value should be a non-negative integer. The default value is 2.
The default cell-vertical-padding method will use this grid-column property, but a custom cell-vertical-padding method may override it.
Function, cg package
Arguments:
Returns the width of vertical scrollbars.
Generic Function, cg package
Arguments: chart-legend
Returns the value of the vertical-spacing property of a chart-legend. The value may be set at creation time by passing the vertical-spacing initarg, or any time later by calling (setf vertical-spacing).
The spacing, measured in pixels, between rows of chart objects in the chart-legend of a chart-widget. The value should be a non-negative integer. The default value is 0.
This property is used only when the draw-legend property of the chart-widget is true.
See also layout-orientation.
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments: window-or-screen
This function simply calls nvirtual-exterior with window-or-screen and a newly-created box. Calling nvirtual-exterior and supplying an existing box (see make-box) instead would avoid consing a box object.
Generic Function, cg package
Arguments: window buttons key-code
This generic function is called when the user presses a keyboard key down. An application may add methods to this generic function to respond to keyboard events in its windows.
window is the window that had the keyboard focus when the event occurred. The keyboard focus is usually indicated by some sort of highlighting.
buttons works as in mouse-left-down, that is it is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
In addition, if the key that was pressed was one of several "extended keys" then the extended-key bit will be set. This is probably useful only when key-code is the value of vk-control or vk-alt and an application needs to know whether the righthand or lefthand version of this key was pressed. For these keys, the extended-key bit will be set for the righthand version only.
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
key-code is an integer representing the key that was pressed. For a letter key, the key code is the char-int of the uppercase character shown on the key (and NOT the corresponding lowercase character). For a numeral key, it is the char-int of the numeral character. For any other key, the key code is the value of the vk- constant for that key (see key-names for a list of vk- constants); for keys that show both a shifted character and an unshifted character, this constant will be named after the unshifted character.
A note about virtual-key-down and character-message:
While a keypress will always cause virtual-key-down and virtual-key-up to be called, it will cause character-message to be called only under certain conditions. First, the keypress must indicate a graphical character. second, one of the following must be true:
The window in which the key was pressed is a dialog-mixin instance or a child or other descendant of a dialog-mixin instance; or
The default virtual-key-down method must run (since this method tells the operating system to generate a character message from the virtual-key-down message).
Therefore, if an application adds a virtual-key-down method for a window that is not on a dialog, and this method does not call (call-next-method) for a particular keypress, then the default virtual-key-down method is not called, and therefore character-message will not be called for that keypress.
See cg-events.html for information about event handling in Common Graphics.
The following is an example from cg-events.html repeated here:
Here's an example that handles the virtual-key-down event, since its arguments are a little tricky. This code will create a window that will change its size when the user types control-L, control-semicolon, control-shift-L, or control-shift-semicolon. The buttons argument is some subset of the values of the constants control-key, shift-key, and alt-key logior'ed together (each one is a bit flag). The data argument is an integer for the key that was pressed, expressed either as the char-int of the character that is printed on the key or as the value of one of the "vk-..." constants that are the value of the constant key-names.
(in-package :cg-user)
(defclass my-window (frame-window)())
(defmethod virtual-key-down ((window my-window) buttons data)
(case buttons
(#.control-key
(case data
(#.vk-semicolon
(incf (width window) 50))
(#.(char-int #\L)
(decf (width window) 50))
(t (call-next-method))))
(#.(logior control-key shift-key)
(case data
(#.vk-semicolon
(incf (height window) 50))
(#.(char-int #\L)
(decf (height window) 50))
(t (call-next-method))))
(t (call-next-method))))
(make-window 'herbert :device 'my-window
:parent (screen *system*))Note that if the example window above were created on (main-development-window *system*) instead of on the screen, then the virtual-key-down method would not get called for the defined keystrokes, because the keystrokes would be overridden by IDE menubar shortcuts. In general, a menubar shortcut will override a virtual-key-down method, and a custom virtual-key-down method will override a comtab binding (since comtab events are implemented as a virtual-key-down method on the general comtab-mixin class).
Generic Function, cg package
Arguments: window buttons key-code
This generic function is called when the user releases a keyboard key. An application may add methods to this generic function to respond to keyboard events in its windows.
window is the window that had the keyboard focus when the event occurred. The keyboard focus is usually indicated by some sort of highlighting.
buttons works as in mouse-left-down, that is it is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:
In addition, if the key that was pressed was one of several "extended keys" then the extended-key bit will be set. This is probably useful only when key-code is the value of vk-control or vk-alt and an application needs to know whether the righthand or lefthand version of this key was pressed. For these keys, the extended-key bit will be set for the righthand version only.
Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,
(logtest right-mouse-button buttons) will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.
key-code is an integer representing the key that was pressed. For a letter key, the key code is the char-int of the uppercase character shown on the key (and NOT the corresponding lowercase character). For a numeral key, it is the char-int of the numeral character. For any other key, the key code is the value of the vk- constant for that key (see key-names for a list of vk- constants); for keys that show both a shifted character and an unshifted character, this constant will be named after the unshifted character.
See cg-events.html for information about event handling in Common Graphics.
Function, cg package
Arguments:
Returns the bottommmost coordinate of all monitors in the system when called on Windows. In CG/JS mode this will always be the same as calling interior-height or exterior-height on the screen.
Function, cg package
Arguments:
Returns the height of all monitors in the system on newer versions of Windows. On Windows with multiple monitors, the value will be the height of the bounding rectangle for all monitors.
See also nvirtual-exterior.
Function, cg package
Arguments:
Returns the leftmost coordinate of all monitors in the system on newer versions of Windows. On Windows with a secondary monitor configured to the left of the primary monitor, the value will be a negative integer whose magnitude is the width of the secondary monitor.
See also nvirtual-exterior.
Function, cg package
Arguments:
Returns the rightmmost coordinate of all monitors in the system when called on Windows. In CG/JS mode this will always be the same as calling interior-width or exterior-width on the screen.
Function, cg package
Arguments:
Returns the topmost coordinate of all monitors in the system on newer versions of Windows. On Windows with a secondary monitor configured above the primary monitor (assuming that that is allowed), the value will be a negative integer whose magnitude is the height of the secondary monitor.
See also nvirtual-exterior.
Function, cg package
Arguments:
Returns the width of all monitors in the system on newer versions of Windows. On Windows with multiple monitors, the value will be the width of the bounding rectangle for all monitors.
See also nvirtual-exterior.
Generic Function, cg package
Arguments: window
Returns a box that indicates what portion of window's page is currently visible within the window, due to its scroll-position and size. The visible box changes when a window is scrolled or resized.
Function, cg package
Arguments: window
Returns the height of the visible-box of window. That box indicates what portion of window's page is currently visible within the window, due to its scroll-position and size. The visible box changes when a window is scrolled or resized.
Function, cg package
Arguments: window
Returns a position object whose coordinates are the top-left of the visible-box of window. That box indicates what portion of window's page is currently visible within the window, due to its scroll-position and size. The visible box changes when a window is scrolled or resized.
Function, cg package
Arguments: window
Returns the width of the visible-box of window. That box indicates what portion of window's page is currently visible within the window, due to its scroll-position and size. The visible box changes when a window is scrolled or resized. See visible-box.
Generic Function, cg package
Arguments: scroll-bar
Starting in release 6.0, this generic function is named thumb-length. visible-portion is maintained as an alternate name, for backward compatibility.
Generic Function, cg package
Arguments: trackbar
Returns the value of the visible-range property of the argument. This property determines a sub-range of a trackbar control's range that is displayed as a bar drawn along the widget.
The visible-range is only displayed when the select-range property of a trackbar has a true value. The value of the visible-range property must be a list of two numbers both within the range of the control.
visible-range is a property of the trackbar class.
Function, cg package
Arguments:
This function may be used to determine whether the user is trying to initiate a drag, rather than performing a simple click. An application may want to initiate a drag-and-drop in a mouse-left-down method only if this function returns true, for example.
wait-for-drag waits until either the left mouse button is up or until the mouse moves at least *start-drag-slack* pixels from where it was when wait-for-drag was called, and then returns. If the left mouse button was pressed when wait-for-drag was called and continues to be pressed until the mouse moves at least start-drag-slack pixels, then true is returned; otherwise nil is returned.
Function, cg package
Arguments:
Waits until no mouse buttons are down and then returns. It may be useful to call this function just before calling a function like get-position or get-box to ensure that a mouse-up from some previous activity does not also terminate the call to get-position or get-box.
Generic Function, cg package
Arguments: chart-widget
Returns the value of the warn-on-insufficient-data property of a chart-widget. The value may be set at creation time by passing the :warn-on-insufficient-data initarg, or any time later by calling (setf warn-on-insufficient-data).
warn-on-insufficient-data is a boolean value indicating whether a warning is signaled when a chart-widget does not have adequate data for drawing itself. The default value is true.
It appears that this warning is currently signaled only if the range-top of a value-axis is not greater than its range-bottom, or if the major-tic-increment is negative.
See chart-widget and also cg-chart-widget.html.
Function, cg package
Arguments:
Returns a pre-defined icon to accompany a warning message to the user. In CG/JS mode this is actually a pixmap, which can be used as an icon in that mode. In Windows desktop mode it is the icon that is the value of the warning-icon variable.
Generic Function, cg package
Arguments: top-level-window window string paste?
This function is called after a copy or paste has been done when running in CG/JS mode, to confirm that the operation was done. An application can add methods to this function that specialize on the app's own window subclasses, to handle these notifications in some custom way.
top-level-window is the top-level-window of the window where the operation was done. This is a parameter to allow specializing methods on that window class when that is more convenient than specializing on the actual window where the operation was done.
window is the window where the operation was done.
string is the text that was copied or pasted.
pasteis true when the operation was a paste andnil` when it was a copy.
Copy & paste is tricky in JavaScript due to security restrictions, and so this function may be useful for confirming that it really happened. Though there is only one known case where it may not actually happen: Some browsers will not do a requested copy if a certain amount of time has passed between when the user typed Control+C (or Command+C on a Mac) and when the event got passed to CG and then CG tells the browser to programmatically do a copy. In that case CG will show a modal dialog that asks the user to type Control+C again while that dialog is present, to let the browser handle the keystroke itself and do the copy. If the user does not follow that instruction and type Control+C again at that time, then no copy will be done, and this generic function will not be called.
Function, cg package
Arguments: &optional (process mp:*current-process*)
This function is meaningful only in CG/JS mode, and will always return nil in Windows desktop mode. In CG/JS mode it will return nil while the web browser is still connected, but return true after the web browser has disconnected. The function windowp will return nil when this function returns true.
If an application user-close method does something that waits on a reply from the user, typically showing a "Do you really want to exit?" dialog, and it may run in CG/JS mode, then it should first call this function and avoid doing the prompt if it returns true. Otherwise it could hang waiting on a reply from the disconnected browser and prevent Lisp from unwinding and exiting (which it normally does when the browser has disconnected).
Function, cg package
Arguments:
Returns a keyword like :chromium, :safari, or :firefox, indicating which brand of web browser the user is using. :chromium is used for all of the Chromium-based browsers, including Chrome, Edge, Opera, Brave, and Vivaldi. Returns nil when running in Windows desktop mode.
Function, cg package
Arguments:
Returns one of the keywords :mac, :windows, or :linux, for the OS of the machine where the user is running their web browser. This can be a different machine than where the CG app is running as a server. Returns nil when running in Windows desktop mode.
Generic Function, cg package
Arguments: calendar-widget
The number of letters in each weekday name to display as column headers in a calendar widget. The default is 2, to display "Su", "Mo", and so on. Using longer strings may require a larger column-padding property when automatic-sizing is enabled.
See also the calendar class and the function ask-user-for-date.
Function, cg package
Arguments: window
This works like mouse-move-filter, except for mouse-wheel events. These events come in when turning an actual mouse wheel, and sometimes are emulated by certain drags on a trackpad.
Generic Function, cg package
Arguments: item-list
Specifies where drag-and-drop should insert dropped values in the list of choices in an item-list, that is a single-item-list or multi-item-list. There are two possible values:
:drop-position - The values will be inserted where the mouse cursor was within the item-list when the user released the mouse button to do the drop.
:pastable-location - The values will be inserted according to the pastable property of the widget, just as if a paste were being done.
Generic Function, cg package
Arguments: window-or-screen position
Returns the uppermost child window of window-or-screen containing position, which is in stream coordinates. Returns nil if position is not inside a window. position must be a position object (see make-position).
Generic Function, cg package
Arguments: dialog-item dialog
Every dialog-item instance that is placed onto a parent window has an associated widget-window or lisp-widget-window instance for the actual window that appears on the screen for the dialog-item. This generic function returns the name of the widget-window class that should be instantiated automatically for a dialog-item. Typically this class is based solely on the class of the dialog-item argument, and the dialog argument is ignored. Here, for example, is the method for radio-button:
(defmethod widget-device ((item radio-button) dialog)
(declare (ignore dialog))
'radio-button-pane)If a widget-window or lisp-widget-window class needs to be subclassed along with a dialog-item class, then a widget-device method should also be written to map the dialog-item subclass to the widget-window subclass.
Most applications are not expected to need to subclass widget-window or lisp-widget-window classes, since the standard behavior built into each dialog-item is provided via the dialog-item instance itself rather than its associated widget-window instance. But if it is necessary to customize a dialog-item by adding methods to low-level generic functions such as mouse-left-down or virtual-key-down, then the widget-window or lisp-widget-window class may be subclassed to provide an application-specific class on which to define these methods.
Here is a simple example that subclasses the standard single-item-list control and causes the numeric keypad keys zero through nine to select one of the first ten values (respectively) in the list. (The NumLock key must first be toggled on if it is off.) A call-next-method allows the arrow keys and first letters of items to move to items as usual.
(defclass berry-list (single-item-list)())
(defclass berry-list-pane (single-item-list-pane)())
(defmethod widget-device ((dialog-item berry-list) dialog)
(declare (ignore dialog))
'berry-list-pane)
(defmethod virtual-key-down ((window berry-list-pane)
buttons key-code)
(declare (ignore buttons))
(if* (<= vk-numpad0 key-code vk-numpad9)
then (let* ((widget (dialog-item window)))
(setf (value widget)(nth (- key-code vk-numpad0)
(range widget))))
else (call-next-method)))
(let* ((item-list (make-instance 'berry-list
:left 20 :top 20 :width 150 :height 200
:range (list 'blueberries 'raspberries 'strawberries
'gooseberries 'huckleberries 'chuckberries
'chuckleberries 'groanberries 'blackberries
'cloudberries)
:value 'raspberries))
(dialog (make-window :berry-list-test
:class 'dialog
:title "Berry List Test"
:width 300 :height 400
:dialog-items (list item-list))))
(select-window dialog)
dialog)Generic Function, cg package
Arguments: widget-window dialog-item new-value old-value recursive-p
This generic function is called by the system when the dialog-item's window is opened and when its range is changed. (The dialog-item is the second argument and its window, the value of (window dialog-item) (see window), is the first argument.) This generic function should not be called by programs and the default method should not be replaced as it updates the screen to reflect the change in the state of dialog-item and returns a true value if the new value is permissible (if it returns nil, the change will be undone). However, after methods may be added to perform other program-specific tasks.
recursive-p will be true when this function is called recursively. In that case, the screen may be up-to-date, and the update function may need to do nothing. This is, however, device-dependent.
Generic Function, cg package
Arguments: widget-window dialog-item new-value old-value recursive-p
This generic function is called by the system when the dialog-item's window is opened and when its value is changed. (The dialog-item is the second argument and its window, the value of (window dialog-item) (see window), is the first argument.) This generic function should not be called by programs and the default method should not be replaced as it updates the screen to reflect the change in the state of dialog-item and returns a true value if the new value is permissible (if it returns nil, the change will be undone). However, after methods may be added to perform other program-specific tasks.
recursive-p will be true if the value of the widget was changed interactively by the user (such as by typing into a text widget) rather than by an application called (setf value). This tells the widget-set-value method that it does not need to update the visible widget-window, because that was done already by the user interaction.
Function, cg package
Arguments: dialog-item
Returns true if subclass-widget has been called on dialog-item more recently than unsubclass-widget has, to indicate that the component is presently receiving all the low-level events normally handled inside the OS where the component is defined.
Function, cg package
Arguments:
Returns the control (widget) under the mouse when this function is called.
Generic Function, cg package
Arguments: value1 value2
This function is used as the initial value for the on-change-test property of a dialog-item. When the two values are both strings, then the result of calling string= on the two values is returned; otherwise the result of calling eql on the values is returned. This special function is provided in order to match string values properly (so strings with identical characters will be considered the same), but without inefficiently recursing into deep trees or other complex widget values needlessly, as equal (which does consider strings with identical characters the same) might do.
This is a generic function, and could be extended with additional methods. For example, if an application often uses RGB color objects as widget values (see make-rgb), then the following method could be added to cause equivalent RGB widget values to always match, without changing the on-change-test property of every widget that might hold RGB's. (eql will always return nil for two RGB objects.)
(defmethod widget-value-equal ((value1 rgb)(value2 rgb))
(rgb-equal value1 value2))Since the on-change-test property is designed to use basic functions like equal that take only two arguments to be compared, there is no dialog-item argument to specialize on and, as a result, this generic function cannot be specialized on particular dialog-item subclasses.
Generic Function, cg package
Arguments: split-bar
Returns the widgets-to-move property of a split-bar widget. The value may be set at creation time by passing the :widgets-to-move initarg to make-instance, or any time later by call (setf widgets-to-move).
This property specifies which widgets and panes on the split-bar's parent window should automatically be moved when the split-bar is moved.
The value should be a list of the names of zero or more of the other widgets (see dialog-item) and/or panes (see basic-pane) that are on the same parent window as the split-bar. The default value is nil. The value may be set at creation time by passing the :widgets-to-move initarg to make-instance, or any time later by call (setf widgets-to-move).
When the user drags the split-bar (or the bar is moved programmatically by calling (setf value)), the widgets and panes in this list will be moved as needed so that they maintain the same distance from the split-bar. For widgets that should be resized instead, use widgets-to-resize.
If this behavior is not adequate, customized effects of dragging a split-bar can be effected by giving the split-bar an on-change function that performs arbitrary side effects.
Generic Function, cg package
Arguments: split-bar
Returns the widgets-to-resize property of a split-bar widget. The value may be set at creation time by passing the :widgets-to-resize initarg to make-instance, or any time later by call (setf widgets-to-resize).
This property specifies which widgets and panes on the split-bar's parent window should automatically be resized when the split-bar is moved.
The value should be a list of the names of zero or more of the other widgets (see dialog-item) and/or panes (see basic-pane) that are on the same parent window as the split-bar. The default value is nil. The value may be set at creation time by passing the :widgets-to-resize initarg to make-instance, or any time later by call (setf widgets-to-resize).
When the user drags the split-bar (or the bar is moved programmatically by calling (setf value)), the widgets and panes in this list will be resized as needed so that their edges that are nearest the split-bar will maintain the same distance from the split-bar. It is a good idea to set the split-bar's min-space-before and/or min-space-after properties to avoid resizing widgets and panes too small.
For widgets that should be moved instead, use widgets-to-move.
If this behavior is not adequate, customized effects of dragging a split-bar can be effected by giving the split-bar an on-change function that performs arbitrary side effects.
Generic Function, cg package
Arguments: standard-object
Returns the value of the width property of the argument. The value of this property is the width in pixels of an object.
Generic Function, cg package
Arguments: dialog-item
Returns the widget-window instance for a widget when it is currently on a parent window, and otherwise returns nil. The argument should be an instance of a dialog-item subclass.
Due to a legacy design decision in Common Graphics, a widget is implemented as two separate objects. The logical object that an application normally deals with is an instance of a dialog-item subclass, and is alternately called either a dialog-item, a widget, a control, or a component in our documentation (though "component" can refer to other interface objects as well).
When a dialog-item is placed onto a parent window (by including it in the :dialog-items argument to make-window or by calling add-component), then the second object, a widget-window instance, is created internally to implement the window that then appears on the screen for the widget. If the parent window is later closed, or if the widget is removed from the parent window by calling remove-component, then the widget-window is destroyed and the window of the widget will again be nil.
Most applications should be able to work with the dialog-item only. If needed, though, an application could pass the window of a widget to any function that takes a window (basic-pane) argument. And if an application needs to add methods to a generic function that will be called on the window of a widget rather than on the widget itself, then the method could specialize on the widget-window class. This generally requires defining subclasses for both the dialog-item class and the widget-window class, and then adding a trivial widget-device method that tells the dialog-item subclass which widget-window subclass to instantiate internally when it is added to a parent window.
Function, cg package
Arguments: window-or-nil ancestor-maybe &key *return-true-if-eq
Returns true if ancestor-maybe is either the parent of window-or-nil, or the parent of the parent, and so on. Otherwise returns nil.
Function, cg package
Arguments: handle
Returns the window whose handle is handle.
Generic Function, cg package
Arguments: window format-string &rest *format-args
Formats a message to the status bar of window if it has one, or else to the nearest ancestor of the window that has a status bar, if any, and otherwise does nothing. The status bar may be either a "regular" status-bar or a common-status-bar. format-string and format-args should be suitable arguments to format.
The return value is true if the message was actually displayed (because some window had a status bar) and nil otherwise.
Generic Function, cg package
Arguments: stream position-or-box
Converts a position-or-box that is in window units (relative to the physical interior upper left corner of the window specified by stream) into screen units (relative to the upper left corner of the screen).
Destructively modifies the position-or-box argument.
Generic Function, cg package
Arguments: stream position-or-box
The name of this function has been changed to device-to-stream-units. See the description of that function for details. The symbol window-to-stream-units continues to name that function as well, for backward compatibility.
Function, cg package
Arguments: from-window-or-screen to-window-or-screen position-or-box
Converts a position or a box that is in window units relative to from-window into window units relative to to-window. The position or box is destructively modified and returned.
Window units are measured in pixels rightward and downward from the interior upper left corner of a window. (Stream units, on the other hand, are measured from the origin of the conceptual "page" or "canvas" that is scrolled within a window, and may be scaled arbitrarily.)
Function, cg package
Arguments:
Returns the window under the mouse when this function is called.
Function, cg package
Arguments: window format-string &rest format-args
Formats a message to the status-bar of window, if there is one, and beeps. It is not an error to apply this function to a window that does not have a status bar but nothing is displayed, of course. format-string and format-args should be suitable arguments to format.
Generic Function, cg package
Arguments: object
Returns true if object is a window or a menu that is open (and therefore still usable), and otherwise returns nil. This may useful for determining whether the owner or parent of a window is a window rather the screen, for example, or whether a known window or menu is still open.
Specifically, true is returned if the object is a cg-stream of the basic-pane class or the menu class, and the stream has not been closed (due to close being called on it), and the process that created it has not been killed.
In CG/JS mode, this function will always return nil if web-browser-has-disconnected returns true.
If an open window or menu's creation-process is killed, then the window is no longer usable, but Common Graphics may not realize that and will continue to regard the window as being an open stream. windowp will catch this situation, though, and will return nil after calling close on the stream so that it is properly closed.
See also screenp.
Generic Function, cg package
Arguments: window-or-screen &key owned-p states
This function returns a list of the child windows or the other owned windows of either a window or the screen.
The order of the windows in the returned list will be the front-to-back occlusion order of the windows.
window-or-screen is the window or screen whose child or owned windows are to be found. (The screen is the value returned by (screen *system*). See screen and *system*.)
If owned-p is nil (the default) then the child windows of window-or-screen are returned. If owned-p is true, then the owned windows of window-or-screen that are not also child windows of window-or-screen are returned. These two groups together comprise all of the owned windows of window-or-screen. Note that only top-level windows can have owned windows that are not also their children; therefore, nil will always be returned if owned-p is passed as true along with a child window or the screen.
states specifies that only windows that are currently in certain states are to be returned. If nil (the default), then windows in all states are returned. Otherwise states may be a list of some combination of the symbols :normal, :shrunk, :icon, and :maximized, in which case only windows that are currently in those states are returned. See state.
Note that if the specified window is a frame-with-single-child window, then its frame-child pane will be included in the returned list, even though it is sometimes considered to be logically a part of the frame window.
See also windows-scratch-list, do-windows, front-window, and next-window.
Function, cg package
Arguments: file-type &key path
This function exists on the Windows platform only.
Returns a command-line string that can be used with run-shell-command (or perhaps the Windows API function WinExec) to invoke whatever program is registered for handling files of a specified file type.
file-type should be a pathname-type string such as "bmp" for Windows bitmap files. The string case does not matter.
path may be a pathname or path namestring of a document to pass as a command line argument to the program, or else nil. If a path, then the returned string is a complete command containing the path, and it may be passed directly to run-shell-command. If nil, then the returned string will contain "%1" where the command line argument would be inserted, if one is accepted.
This form uses run-shell-command to invoke the registered PDF-displaying program to display the AllegroCache tutorial. (The :winapi module must be loaded; evaluate (require :winapi).)
;; The winapi module must be loaded for these examples to work
(require :winapi)
(run-shell-command
(windows-command-for-document-type
"pdf"
:path (merge-pathnames
"acache/doc/acachetutorial.pdf"
(translate-logical-pathname "sys:"))))This form does the same thing using WinExec.
(with-native-string
(native (windows-command-for-document-type
"pdf"
:path (merge-pathnames
"acache/doc/acachetutorial.pdf"
(translate-logical-pathname "sys:"))))
(win:WinExec native win:SW_SHOWNORMAL))(setf windows-command-for-document-type) can be called to register a particular program for some file type. This setf function does not have the path argument. The file-type argument should be the same as above, and the value should be the command line string to execute for that file type. This sets the global registry value for the file type, and so it should not be done without an explicit request from the user.
Function, cg package
Arguments: parent-stream &key owned-p states
This function is the same as the more common function windows, except that it avoids consing the returned list of windows by destructively modifying and returning a single internal "scratch list". Care must be taken if using this function, since any subsequent call in the same thread to either windows-scratch-list (this function) or windows, even by internal Common Graphics code, will effectively destroy the returned value. It is probably useful only in tight loops where the returned list is referenced immediately and disregarded thereafter.
Macro, cg package
Arguments: (window color) &body body
The background-color of window is set to color during the evaluation of body, and then restored to window's original background color. color must be a color-number, a RGB color, or nil. nil means use the system background color.
Note: Monochrome devices which support reverse video will generally have a two color (black and white) palette. Reverse video can be achieved by swapping foreground and background color-numbers.
Macro, cg package
Arguments: (stream texture) &body body
Evaluates body with the background-texture of stream set to texture. Restores the stream's previous background-texture at the end and returns the values that the body returns.
stream may be any graphical-stream.
texture should be a valid value for (setf background-texture).
See also with-fill-texture and with-line-texture, and also with-background-color and with-foreground-color.
Macro, cg package
Arguments: (&rest box-variables) &body body
This macro and the related with-positions and with-positions-and-boxes stack-allocate position and/or box objects to provide temporary objects without consing, thereby possibly reducing the time spent garbage collecting.
The objects are valid only through the dynamic extent of the macro call, and unpredictable errors may occur if they are referenced afterward. Further, functions such as typep and boxp that query the type of an object should not be used on objects created by this macro. Type information for such objects is sacrificed to achieve the non-consing efficiency of stack allocation, and the return values from such type-checking calls are undefined.
Note that now that Common Graphics is multithreaded, the use of the alternative technique of placing position and box constants in source code via the #. reader macro, as in #.(make-box 0 0 10 10), is now strongly discouraged due to potential re-entrancy conflicts.
See the example using boxes and positions in with-positions-and-boxes.
See About using multiple threads in the IDE in cgide.html.
macro, cg package
Arguments: &body body
This macro allows establishing the Common Graphics variable bindings in an existing process where it is not feasible to pass *default-cg-bindings* at process creation time.
The following example should work in an arbitrary process that was not created with the *default-cg-bindings*. This form will return only when the user closes the window that it creates.
(with-cg-bindings
(let* ((window (make-window :foo :title "Close Me")))
(event-loop :window window)))Macro, cg package
Arguments: (stream box) &body body
Sets the clipping box for stream to box for the evaluation of body, and then restores the clipping box to its original value. unwind-protect is used to ensure that the clipping box is restored. See clipping-box.
box should either be a box (see make-box) to establish clipping, or else nil to remove all clipping. stream should be a cg-stream.
Macro, cg package
Arguments: (cursor) &body body
Changes the mouse cursor to cursor during the execution of body. Note that you should wrap this macro only around code where you do not intend to release the processor to handle other events (as with a call to process-pending-events). During the execution of the body, mouse and keyboard events will be queued as usual.
cursor should be one of the standard mouse cursors or a cursor that was created with make-instance as described in the pixmaps overview.
During the evaluation of body, the cursor will be the value of the variable *with-cursor*.
If you want to return to standard cursor behavior during the execution of body, use without-cursor.
Macro, cg package
Arguments: (object &key invalidate invalidate-frame invalidate-children) &body body
Disables drawing on object and its child windows during the execution of body. object may be a window or a dialog-item (control). In effect, delay-redraw is called on object prior to the evaluation of body and resume-redraw is called after body completes.
with-delayed-redraw returns the values returned by the body.
This macro may be useful for preventing redundant redisplaying of windows, which can slow down an interface and be visually annoying. All output to the window or control will be prevented, whether it is the operating system redisplaying a control that it implements, or application code redisplaying a "regular" window.
The keyword arguments allow invalidation of the object's interior, frame, and/or child windows when the with-delayed-redraw form is exiting so that the window(s) will be notified to redisplay themselves once in their entirety after the body has executed. (Certain controls implemented in the operating system may redisplay themselves at the end anyway, making it unnecessary to pass any invalidate flags.)
with-delayed-redraw has special behavior for a bitmap-pane. While drawing is disabled on the window itself, it is not disabled on the window's backing-store memory bitmap. This feature can be used to quickly switch a bitmap-pane to a new "scene" by drawing the new scene inside a with-delayed-redraw form, and passing the invalidate flag so that the memory bitmap is copied in one step to the visible window once the scene is drawn. This speeds up the drawing on the bitmap-pane, and removes the annoying flash that can occur when one scene is erased before the next is drawn.
For example, suppose bw is a bitmap-window and bp its bitmap-pane:
(setq bw (make-window :bw :class 'bitmap-window))
(setq bp (frame-child bw))The following form draws colored circles over bp:
(progn (clear-page bp)
(let ((lis (list red cyan yellow black green blue)))
(dotimes (i 100)
(let ((color (nth (mod i 6) lis))
(center (make-position
(+ 50 (* 100 (truncate (/ i 10))))
(+ 50 (* 50 (mod i 10))))))
(setf (foreground-color bp) color)
(fill-circle bp center 40)))))If you evaluate that form, you may (depending on your display and processor speed) see intermediate displays and/or flashes. Now do:
(clear-page bp)
(with-delayed-redraw (bp :invalidate t)
(progn (clear-page bp)
(let ((lis (list red cyan yellow black green blue)))
(dotimes (i 100)
(let ((color (nth (mod i 6) lis))
(center (make-position
(+ 50 (* 100 (truncate (/ i 10))))
(+ 50 (* 50 (mod i 10))))))
(setf (foreground-color bp) color)
(fill-circle bp center 40))))))Note that the display updates all at once when it updates.
When a window other than a bitmap-pane is inside a with-delayed-redraw, Windows appears to suppress redrawing by claiming that the window is hidden. One odd symptom of that design is that if something is drawn on a window that is immediately behind a window that is inside a with-delayed-redraw, the drawing will appear on the screen as if the delayed window were not there at all. For this reason, the double-buffered feature may be a preferable alternative to with-delayed-redraw for windows other than bitmap-panes.
Macro, cg package
Arguments: (hdc-var window &optional non-client-p) &body body
A macro that ensures that window has a device-context while body is executed. While generic windows do have permanent device-contexts in common graphics, controls that are implemented by the operating system do not. If you need to draw on a window that might be a Windows control, then you probably need to wrap the drawing code inside a with-device-context call. If you want to draw on the screen, over any windows that are displayed, you need to wrap the drawing code in a with-device-context form as well. See the information under `Drawing on the screen' below.
If window does already have a device-context, then the hdc-var variable is bound to that existing device-context and the body is executed. If window has no device-context, then one is created for it and stored as the device-context property of the window while body is executed, then the device-context is removed from the window and destroyed, leaving the device-context of window as nil.
If non-client-p is true, then the hdc-var variable will be bound to a non-client device-context (for drawing on the frame of the window) rather than a client-area device-context as usual. Also, if the window has a device-context already, a fresh non-client device-context will always be used in place of the existing client-area device-context of the window, which will be returned to the window after the execution of body. So with-device-context is still needed for drawing on a generic window that already has a device context if the drawing is to be done on the frame (or border) of the window.
From the description of device-context:
Returns an integer that identifies the device-context of window if it has one, or nil otherwise. A device-context is a construct used in the Windows API to specify a set of parameters that are used when drawing on a window. A common graphics application does not normally need to deal with a window's device-context directly, but if you need to pass the window to a winapi function that calls for the window's device-context (or hDC), then you should pass the integer returned by this function for that argument. handle returns the window's "handle".
Every non-control window in common graphics (and every lisp-widget window) is automatically assigned a device-context, which it keeps until it is closed. Controls supplied by the OS (all controls except lisp-widgets), on the other hand, are not automatically given device-contexts in Lisp since it is normally only the OS rather than Lisp that draws on the control. If you do want to draw directly on a non-Lisp control, then you must give the window of the control a device-context while drawing on it. The easy way to do this is to wrap a call to with-device-context around the code that draws on the control.
A with-device-context form is also needed in order to draw directly on the screen (over any windows that happen to be where the drawing is done). Any current drawing attributes such as line-width or font must also be set up within the same with-device-context form as the drawing that uses it. If drawing is attempted on the screen without setting up the device-context, an error dialog will appear noting that with-device-context needs to be used.
In the past, the screen was internally given a permanent device context as with regular windows, but the device context eventually became invalid at some unpredictable time.
The Common Graphics utility functions such as get-line and get-shape-box are often used to draw rubber-banding lines directly on the screen; these utilities set up the needed device context for the screen internally.
(let* ((screen (screen *system*)))
(with-positions (pos1 pos2) ;; to avoid consing
(with-device-context (hdc screen)
(with-foreground-color (screen blue)
(dotimes (j 11)
(draw-line screen (nmake-position pos1 100 200)
(nmake-position pos2 (+ 100 (* j 10)) 300))))
(with-foreground-color (screen dark-green)
(dotimes (j 11)
(draw-line screen (nmake-position pos1 200 300)
(nmake-position pos2 (+ 100 (* j 10)) 200)))))))Macro, cg package
Arguments: (window) &body body
This macro should not be needed by most applications. Normally you would achieve double-buffering by enabling the double-buffered property of a window and ensuring that you draw in the window only in a redisplay-window method that Common Graphics calls automatically. See double-buffered for complete information about this property.
But if for some reason you need to draw on a window directly rather than using the usual redisplay-window callback paradigm, and you still want to use double-buffering, then you can do so by wrapping a call to with-double-buffering around the drawing code. This macro will copy the window's memory bitmap to the visible window at the end of its body, just as Common Graphics otherwise does just after it has called redisplay-window.
When using with-double-buffering, the double-buffered property of the window must still be true in order for double-buffering to occur.
Macro, cg package
Arguments: (window &key draw fill) &body body
Calls begin-drawing-path and end-drawing-path to collect all of the line-drawing output within body into a "path", which is then drawn and/or filled as a unit. An unwind-protect ensures that end-drawing-path is always called for each call to begin-drawing-path.
A path is useful for filling a collection of lines and curves as a unit.
Refer to begin-drawing-path and end-drawing-path for more information.
See also line-end, with-line-end, line-join, and with-line-join.
Macro, cg package
Arguments: (window) &body body
If event handling is currently enabled on window, calls enable-events before and after executing the body, passing the enable-p argument to that function as nil (disabling events) and then t (re-enabling events) in order to suppress the handling of mouse clicks, keystrokes, and other events sent to the specified window during the execution of the body.
An unwind-protect is used to ensure that events are re-enabled at the end. Returns whatever values are returned by the body.
If event handling is currently already disabled on window, then the body is simply executed and nothing else is done.
You can use with-events-enabled within body to temporarily re-enable events during the execution of body.
Macro, cg package
Arguments: (window) &body body
If event handling is currently disabled on window, calls enable-events before and after executing the body, passing the enable-p argument to that function as t (enabling events) and then nil (re-disabling events) in order to enable the handling of mouse clicks, keystrokes, and other events sent to the specified window during the execution of the body. This may be useful for enabling events during a portion of a period where they are otherwise disabled by a surrounding call to with-events-disabled.
An unwind-protect is used to ensure that events are re-disabled at the end. Returns whatever values are returned by the body.
If event handling is currently already enabled on window (as it is by default), then the body is simply executed and nothing else is done.
Macro, cg package
Arguments: (stream texture) &body body
Evaluates body with the fill-texture of stream set to texture. Restores the stream's previous fill-texture at the end and returns the values that the body returns.
stream may be any graphical-stream.
texture should be a valid value for (setf fill-texture).
See also with-background-texture and with-line-texture, and also with-background-color and with-foreground-color.
Macro, cg package
Arguments: (window font) &body body
Executes body with the font of window set to font. After executing the body, the font of window is set to its former value, and with-font returns what body returns. font should be a font object as created with make-font-ex or make-font.
Macro, cg package
Arguments: (window color) &body body
The foreground-color of window is set to color during the evaluation of body, and then restored to window's original foreground color. color must be a color-number, a RGB color, or nil. nil means use the system foreground color.
Note: Monochrome devices which support reverse video will generally have a two color (black and white) palette. Reverse video can be achieved by swapping foreground and background color-numbers.
Macro, cg package
Arguments: &body body
Changes the mouse cursor to an hourglass (the waiting-cursor) during the execution of body. Note that you should wrap this macro only around code where you do not intend to release the processor to handle other events (as with a call to process-pending-events). During the execution of body, mouse and keyboard events will be queued as usual.
Macro, cg package
Arguments: (window dashing) &body body
Evaluates body while the default line dashing of window is dashing.
Suitable values of dashing are:
:solid
:dot
:dash
:dash-dot
:double-dot
:long-dash
:dash-double-dotSee line-dashing.
Macro, cg package
Arguments: (window line-end-style) &body body
Evaluates body while the line-end style of stream is line-end-style.
Restores the previous line-end style upon exiting, returning whatever body returns.
See also line-join, with-line-join, begin-drawing-path, end-drawing-path, and with-drawing-path.
Macro, cg package
Arguments: (window line-join-style) &body body
Evaluates body while the line-join style of stream is line-join-style.
Restores the previous line-join style upon exiting, returning whatever body returns.
See also line-end, with-line-end, begin-drawing-path, end-drawing-path, and with-drawing-path.
Macro, cg package
Arguments: (stream texture) &body body
Evaluates body with the line-texture of stream set to texture. Restores the stream's previous line-texture at the end and returns the values that the body returns.
stream may be any graphical-stream.
texture should be a valid value for (setf line-texture).
See also with-fill-texture and with-background-texture, and also with-background-color and with-foreground-color.
Macro, cg package
Arguments: (window line-width) &body body
Evaluates body while the default line width of window is width. A width of 0 means draw the thinnest line possible. See line-width.
Macro, cg package
Arguments: (string-or-pixmap &key (owner '(screen *system*)) width height (horizontal-margin 24) (vertical-margin 24) (background-color 'yellow) (foreground-color 'black) (font (make-font-ex nil "Arial" 20 '(:bold))) (border :black) class) &body body
This is a convenience utility macro that displays a simple message window while some activity is taking place, typically to tell the user to wait until the activity has finished. Unlike a modal dialog (see pop-up-modal-dialog and pop-up-message-dialog), the message window does not wait for the user to interactively respond to the message before proceeding. Instead, it simply displays the message window, then proceeds to run the macro body, and finally removes the message window automatically when the body has completed. It returns whatever the body returns. (Such a window is useful when a progam is performing an action that may take a user-noticeable amount of time.)
The required string-or-pixmap is either a string or a pixmap to display in the message box. A non-null value for this argument must be supplied.
The keyword arguments are:
owner is the window or screen on which to display the message box. The message box will be centered within this owner. The default is value is the screen.
width is either an integer specifying the pixel width of the message window, or else nil to default to a particular portion of the owner's width. The default value is nil. If the first argument is a pixmap rather than a string, then the width argument is ignored and the window width will instead be the width of the pixmap plus the specified horizontal margins.
height is either an integer specifying the pixel height of the message window, or else nil to default to whatever height is necessary to contain the message string or pixmap, given the window's width, margins, and font that are determined beforehand. If the first argument is a pixmap rather than a string, then the height argument is ignored and the window height will instead be the height of the pixmap plus the specified vertical margins.
horizontal-margin is the pixel width of blank space to leave between the left and right borders of the message window and the text or pixmap inside. The default is 24.
vertical-margin is the pixel height of blank space to leave between the top and bottom borders of the message window and the text or pixmap inside. The default is 24.
background-color is the color of the background of the message window. It is either an RGB color object (see make-rgb) or else nil to default to the system-background-color. The default is the value of the constant yellow.
foreground-color is the color of the string that is drawn in the message window (unless a pixmap is specified instead). It is either an RGB color object (see make-rgb) or else nil to default to the system-foreground-color. The default is the value of the constant black.
font is the font in which to draw the string (unless a pixmap is specified instead), or else nil to default to the font returned by proportional-font. The default is the relatively large font returned by (make-font-ex nil "Arial" 20 '(:bold)) (see make-font).
border is the type of border that the message window will have. The default is :black to draw a thin border. See the border property of windows for other valid values.
class is the name of the window class to use for the message window. If nil or unspecified, it defaults to message-window. To change the appearance of the window, an application could define a subclass of message-window with default-initargs for various properties, and then pass the name of that subclass to with-message-window.
with-message-window calls the function make-message-window to make the actual window. If you would like to display the message window at some time other than during the execution of a macro body, then you could call that function directly instead.
Here is a complete example for with-message-window. A window is displayed and lines are drawn in it. A message window is also displayed asking the user to wait while the lines are drawn. The drawing is slowed by calls to sleep (in order for the example to show the message window for a noticeable time).
(with-positions (first-position previous-position next-position)
(let* ((width 300)(height 400)
(dx 3)(dy 4)(resolution 8)
(frame (make-window :frame
:class 'bitmap-window
:title "My Main Window"
:interior (make-box-relative 100 100 width height)))
(pane (frame-child frame)))
(nmake-position first-position (round width 2) height)
(ncopy-position previous-position first-position)
(with-message-window
("Please wait while this application draws a bunch of lines."
:owner frame
:width 200
:font (make-font-ex nil "Arial" 17)
:background-color green)
(flet ((draw-mirrored-line
(stream pos1 pos2 width)
(with-positions (mpos1 mpos2)
(draw-line stream pos1 pos2)
(draw-line stream
(nmake-position mpos1
(- width (position-x pos1))
(position-y pos1))
(nmake-position mpos2
(- width (position-x pos2))
(position-y pos2))))))
(dotimes (j 40)
(sleep 0.1) ;; artificially slow this down
(dotimes (k 4)
(nmake-position next-position
(+ (max (* resolution dx)
(min (- width (* resolution dx))
(position-x previous-position)))
(* resolution (- (random (1+ (* 2 dx))) dx)))
(+ (max (* resolution dy)
(min (- height (* resolution dy))
(position-y previous-position)))
(* resolution (- (random (1+ (* 2 dy))) dy))))
(draw-mirrored-line pane previous-position next-position width)
(ncopy-position previous-position next-position)))
(draw-mirrored-line pane next-position first-position width)))))Macro, cg package
Arguments: (text-edit-pane &key invalidate) &body body
Evaluates body while all text controls (parenthesis matching, cursor flashing, etc.) are disabled.
Macro, cg package
Arguments: (window) &body body
This macro calls capture-mouse and release-mouse around its body, using an unwind-protect to ensure that the release is always done. capture-mouse causes all mouse events to be directed to the specified window rather than to whatever windows are under the mouse cursor.
An exception is that left-clicking on another window will still expose it. If nested calls to with-mouse-captured are made, then returning from the inner call will restore the capture to the window of the outer call. nil can be passed for window in an inner nested call to with-mouse-captured to temporarily remove the capture of the outer call.
Macro, cg package
Arguments: (window &optional box) &body body
Confines the mouse cursor to the region of window specified by box while the body of the macro is executed. When you use this macro, you are guaranteed that the cursor will be freed even if an error occurs in body. Note that confining the mouse is considered by some to be an unfriendly technique (because it prevents using other Windows programs).
The window argument denotes the window within which to confine the mouse cursor. The box argument denotes a region with respect to the exterior of window, and will default to the exterior region of window. Therefore, not passing the box argument will confine the mouse to within the exterior edge of window.
The box argument, if supplied, may be modified by this macro. If you wish to reuse box, copy it before passing it to this macro.
macro, cg package
Arguments: (stream gradient-name) &body body
Causes filling functions like fill-box in body to use a special hardcoded gradient effect during the execution of body.
Executes body and returns its values, first passing the other arguments to a call to set-named-gradient, and making a corresponding protected call to clear-named-gradient at the end.
An exception is that if gradient-name is nil, then the body is still executed but set-named-gradient and clear-named-gradient are not called. This allows deciding at run time whether to actually establish a gradient.
This macro is implemented only on Windows and JavaScript/HTML.
See also named-gradient.
Macro, cg package
Arguments: (object) &body body
Executes body with *locale* bound to the object-locale of object if it is non-nil, and otherwise to the current value of *locale*. Returns whatever the body returns. See object-locale for more information.
Macro, cg package
Arguments: (stream-var &rest printer-args &key units-per-inch font (cancel-value :cancel) (printer-class 'printer) &allow-other-keys) &body body
Executes body with stream-var bound to a newly-opened printer stream. The printer-args parameter allows any initargs that would be passed to open-stream for a printer to be passed to this macro. In addition, if units-per-inch is specified true, then the stream-units-per-inch of the printer stream is set to this value before executing body. If a font is passed, then the font of the printer stream is set to this font before executing body (just after the stream-units-per-inch is set, if this is also done). If printer-class is specified, it should be the name of the printer stream class to be instantiated, which should always be a subclass of the printer class (or that class itself).
When the printer stream is opened, the end user is presented with the printer job dialog as usual (unless the :no-dialog-p printer-arg is passed as true). If the user cancels from this dialog, then cancel-value is returned from the with-output-to-printer form.
Otherwise the values returned by the last form in body are returned. An unwind-protect ensures that the printer stream always gets closed.
The following example does the following:
opens a printer stream,
sets its stream-units-per-inch to 100 (which scales it approximately the same as a video monitor),
sets its font to be a large arial font which is 48 of these stream units tall,
prints "A Large String" on the printer stream,
closes the printer stream (which ejects the output).
(with-output-to-printer (p :units-per-inch 100
:font (make-font-ex nil :arial 48))
(print "A Large String" p))That returns "A Large String"
See also with-printer.
Macro, cg package
Arguments: (window operation) &body body
The paint-operation of window is set to operation during the evaluation of body, and then restored to window's original paint operation.
Macro, cg package
Arguments: (&rest position-variables) &body body
This macro and the related with-boxes and with-positions-and-boxes stack-allocate position and/or box objects to provide temporary objects without consing, thereby possibly reducing the time spent garbage collecting.
position-variables are just symbols which name positions in the body of the macro. Use nmake-position to supply them with x and y values (see the example below).
The objects are valid only through the dynamic extent of the macro call, and unpredictable errors may occur if they are referenced afterward. Further, functions such as typep and positionp that query the type of an object should not be used on objects created by this macro. Type information for such objects is sacrificed to achieve the non-consing efficiency of stack allocation, and the return values from such type-checking calls are undefined.
Note that now that Common Graphics is multithreaded, the use of the alternative technique of placing position and box constants in source code via the #. reader macro, as in #.(make-position 0 0), is now strongly discouraged due to potential re-entrancy conflicts.
Example:
(defun draw-diagonal-in-box (window box)
;; Avoids consing positions, as when calling box-top-left
(with-positions (tpos1 tpos2)
(draw-line window
(nmake-position tpos1 (box-left box)(box-top box))
(nmake-position tpos2 (box-right box)(box-bottom box)))))See About using multiple threads in the IDE in cgide.html.
Macro, cg package
Arguments: (&rest position-variables) (&rest box-variables) &body body
This macro and the related with-positions and with-boxes stack-allocate position and/or box objects to provide temporary objects without consing, thereby possibly reducing the time spent garbage collecting.
position-variables and box-variables are just symbols which name positions in the body of the macro. Use nmake-position to supply the positions with x and y values and nmake-box to supply the boxes with left, top, right, and bottom values (see the example below).
The objects are valid only through the dynamic extent of the macro call, and unpredictable errors may occur if they are referenced afterward. Further, functions such as typep, boxp, and positionp that query the type of an object should not be used on objects created by this macro. Type information for such objects is sacrificed to achieve the non-consing efficiency of stack allocation, and the return values from such type-checking calls are undefined.
Note that now that Common Graphics is multithreaded, the use of the alternative technique of placing position and box constants in source code via the #. reader macro, as in #.(make-box 0 0 10 10), is now strongly discouraged due to potential re-entrancy conflicts.
Example:
(defun is-pos-in-box (x y left top right bottom)
;; Avoids consing a position and a box.
(with-positions-and-boxes (tpos) (tbox)
(inside-box-p (nmake-position tpos x y)
(nmake-box tbox left top right bottom))))
;; Load and compile, and then:
cg-user(35): (time (is-pos-in-box 10 20 15 15 30 30))
; cpu time (non-gc) 0.000000 sec user, 0.000000 sec system
; cpu time (gc) 0.000000 sec user, 0.000000 sec system
; cpu time (total) 0.000000 sec user, 0.000000 sec system
; real time 0.000000 sec
; space allocation:
; 0 cons cells, 0 other bytes, 0 static bytes
; Page Faults: major: 0 (gc: 0), minor: 0 (gc: 0)
nil
cg-user(36): (is-pos-in-box 10 20 5 5 30 30)
t
cg-user(37): See About using multiple threads in the IDE in cgide.html.
Macro, cg package
Arguments: (stream-variable &rest printer-args &allow-other-keys) &body body
This macro allows opening a printer stream to query its properties without ejecting any paper from the printer as with-output-to-printer (or open-stream followed by close) does. This may be useful, for example, for implementing a Print Preview dialog, where you must know the available drawing area of a printer before an actual print is done.
(In the past, it has been possible to close a printer stream without ejecting paper from the printer by passing the :abort argument to close as true. It appears that this technique does not work in Windows 2000, however, so that functionality has been deprecated in favor of this new macro, which requires that an application indicate at the outset that a printer stream is not for actual printing.)
with-printer accepts the same arguments as with-output-to-printer, most of which are documented under pop-up-printer-job-dialog. In particular, most applications will probably want to pass the no-dialog-p keyword printer argument as true in order to silently query a printer without showing the Print Job dialog to the user.
It may be desirable to pass certain printing arguments that are to be used later when actually printing, in order to query the printer attributes of interest in that context. Doing this will not change the default values of these arguments for subsequent printing though.
Here's an example that returns the name of each installed printer along with its resolution and its margin properties that denote the range of stream units within which an application should draw on that printer. The returned values reflect the :landscape orientation that is passed in. (See *default-printer-left-margin* for an explanation of how Common Graphics sets up the initial margin properties of a printer.)
(mapcar #'(lambda (name)
(with-printer (out :printer-name name
:orientation :landscape
:no-dialog-p t)
(list (printer-name out)
(stream-units-per-inch out)
(left-margin out)(top-margin out)
(right-margin out)(bottom-margin out))))
(printer-names))Macro, cg package
Arguments: (rgb-variable) &body body
Executes body with rgb-variable bound to a temporarily allocated RGB object. This allows using an RGB without consing one that would need to be garbage collected.
Typically the body code would initialize the RGB object by calling make-rgb, passing rgb-variable as the value of the scratch-rgb argument along with the desired red, green, and blue values. Alternately it could be initialized by calling (setf rgb-red), (setf rgb-green), and (setf rgb-blue).
Macro, cg package
Arguments: (object slotname value) &body body
Evaluates body while the value of the slotname slot of object is value. The original slot value is restored when body completes or if evaluating body signals an error.
Macro, cg package
Arguments: &body body
This macro is for use within the body of a with-cursor form. While the body of this macro is being evaluated, the mouse cursor specified in the with-cursor form will be suppressed and standard cursor behavior will be in effect. (Note: the name of this macro may be confusing because it could be interpreted to mean no cursor will be visible while body is executed. That is an incorrect interpretation.)
Macro, cg package
Arguments: (&rest widgets) &body body
This macro is useful for suppressing the usual running of the on-change code of one or more widgets while a body of application code is executed.
Evaluates body while the value of the on-change event handler property for each dialog-item in widgets is temporarily set to nil. Returns whatever the last form in body returns.
The original value of each on-change event handler is restored when body completes. An unwind-protect ensures this restoration in case of a break or a throw in body.
Each value in the widgets list should be an expression that evaluates to either a dialog-item instance or to nil. When nil, nothing is done for that member of the list.
(without-on-change (widget1)
(do-something)
(do-something-else))
(without-on-change ((find-component :widget1 my-dialog))
(do-something))
(without-on-change (widget1 widget2
(find-component :widget3 my-dialog)
(find-component :widget4 my-dialog))
(do-something))macro, cg package
Arguments: (lisp-edit-pane &key no-draw) &body body
Executes body with parenthesis matching disabled in lisp-edit-pane. This means that no search will be done for matching parentheses or double-quote marks, and so parenthesis-matching marks will not be drawn or erased, and parentheses-matched will not be called.
This macro may be useful to avoid wasting time searching for matching parentheses within code that is moving the text cursor around in a lisp-edit-pane, or to avoid flashing effects as the text cursor is moved to multiple positions that may be next to parentheses or double-quote marks on literal strings. See also with-motionless-text-control (which always calls this macro internally).
If no-draw is nil (the default), then any parenthesis-matching mark that was visible in the window will be erased before the body is executed, and the usual parenthesis-matching check will be made afterward at the current text cursor position, drawing the usual mark if needed. If no-draw is true, then neither of those things is done. Drawing glitches could result if no-draw were always passed as true, but you may pass it as true if you know that the text cursor will be at the same index on entry to and exit from the body (and the characters on either side of the text cursor will be the same); this may avoid a needless redrawing of the parenthesis-matching mark.
Generic Function, cg package
Arguments: widget
Returns the value of the wrapping property of the argument. wrapping is a property of the following classes:
The meaning is different for up-down-control than for the other classes. The default value is t for static-text and scrolling-static-text and is nil for the others.
The wrapping property cannot be modified on an existing control by calling (setf wrapping). Instead it must be specified by passing the :wrapping initarg to make-instance when creating the control. (When using the inspector to interactively edit controls on a form, the inspector can still make such modifications because it internally recreates the control's window to reflect the change and creates the make-instance form to create the control in the actual application.)
An up-down-control allows the user to change the (typically) numeric value in an editable-text control by clicking on an up arrow or a down arrow displayed on the up-down control. The issue with wrapping is what happens when the user clicks the up arrow when the value is at the top of the range or clicks the down arrow when the value is at the bottom of the range.
If the wrapping property is true, clicking the up arrow when the value is at the top of the range changes the value to the bottom of the range while clicking the down arrow at the bottom changes the value to the top. If wrapping is nil, clicking an arrow when the value is at the extreme of the range has no effect.
If the wrapping property on one of these controls is true (the default for static-text and scrolling-static-text but not for the others), the text (in the title of the various button controls and the value of static-text controls) is automatically wrapped at spaces as necessary to prevent the text from extending beyond the right edge of the control. If nil, the text is displayed on a single line up to the point where the text is clipped at the right edge of the control. Turning this property off can be useful for a static-text that displays only a single line of text so that a long word that would otherwise be wrapped to the next (unseen) line will instead remain on the first line to be visible up to the point where it is clipped by the right edge of the control.
Function, cg package
Arguments: condition
This is an alternate value for the default-error-handler-for-delivery option of a project, for debugging a generated application that crashes or fails to start up. When an otherwise unhandled error is signaled, it will print the current function stack backtrace into a file named cg-backtrace.txt in the system temporary directory, where that path is returned by this expression:
(merge-pathnames "cg-backtrace.txt" (sys:temporary-directory))The application will continue to run after this, though it may be in an inconsistent state. The only sign that an error has occurred may be that the generated app stops responding; in that case, you could check the content of that file (if it exists) when using this function.
Generic Function, cg package
Arguments: cg-configuration
This option has an effect only on the Windows platform.
This CG configuration option determines whether the function save-file will write UTF8 byte order marker (BOM) bytes at the beginning of the file, if the file is being saved in UTF8 format (see external-format-for-saved-files and external-format-for-save). This affects the IDE's source code editor as well as calling save-file on a text-edit-pane in a CG application.
This option is true by default so that any software that reads the file can unambiguously determine that the file's format is UTF8. Some file-reading software may stumble over the BOM bytes, though, in which case you could turn this option off if you need to transfer saved files to such software. But note that if you turn this option off and do not also turn on load-utf8-if-no-bom, then load-file would not correctly reload a file that was saved with save-file in UTF8 format if it contains any non-ASCII characters; this affects the IDE's source code editor as well.
This option can be found on the Editor tab of the IDE's Options dialog.
Generic Function, cg package
Arguments: grid-row grid-column row-number column-number value
This generic function may be called to write a value that the user has interactively entered into the grid cell defined by the row and column arguments back into an application's back into an application's master data, or else to save the values within the grid-widget itself by default. The grid-row and grid-column arguments are objects such as are returned by calling subsections on a grid-row-section or grid-column-section. (An alternative function where you can instead pass row and column names or indexes is the setf of cell-value.)
The row-number and column-number arguments define which replication of replicated rows or columns is being addressed (see section-count).
Typically write-cell-value is called by a cell-click method or a cell-key-down method that has interpreted a new cell value from the end user's mouse or keyboard gesture. If the grid column uses one of the built-in grid-column classes such as editable-text-column-mixin, then the cell-click or cell-key-down method that is supplied with the built-in column class will call write-cell-value internally. Otherwise an application may supply custom cell-click or cell-key-down methods that call write-cell-value. The default write-cell-value method (shown below) first looks for the common grid paradigm where each grid row represents a data object (such as an employee) and each grid column represents an attribute of those objects (such as an employee's department). Next it will check if the (more obscure) data-slot approach is being used. Last, if nothing has been set up for writing the value back into application data, it will save the value within the grid-widget itself; in this case the application can call cell-value or read-cell-value later to retrieve the current value of the cell.
(defmethod write-cell-value ((row grid-row)(column grid-column)
row-num column-num value)
(declare (ignore row-num column-num))
;; This is default write-cell-value method, which is called to write
;; a value that's displayed in a grid cell back to wherever it is officially
;; stored within the application, when no more specific write-call-value
;; method has done that.
;; First, if the grid-row has a data-object that holds values to display
;; in that row, and the grid-column has a data-writer function to write that
;; column's values into objects, then write the value in that way.
(let* ((data-object (data-object row))
(data-writer (data-writer column))
(slot-spec (data-slot column)))
(cond ((and data-object data-writer)
(funcall (cond ((functionp data-writer) data-writer)
(t (fdefinition data-writer)))
value data-object))
;; If the column does not have a data-writer, but it does have
;; a data-slot specifier (for following a path to the destination
;; slot), then go with that.
((and data-object slot-spec)
(setf (direct-or-indirect-slot-value
data-object slot-spec)
value))
;; In the end, if no special means has been set up for writing the
;; cell value into the application's own data, then store the value
;; within the grid-widget itself. This is internal functionality
;; that stores the value in a plist on the grid-row, where the key
;; is the grid-column.
(t (setf (getf (cell-values row) column) value)))))The default method may be used for cells that fit this paradigm if the application has therefore supplied data-object values for the grid rows and data-writer functions for the grid columns. For grids that do not fit the object-rows-and-attribute-columns paradigm, the application could either supply a write-cell-value method that writes grid data to the application in a custom way, or else not use write-cell-value at all in its cell-click and cell-key-down methods.
Even if you can use the default write-cell-value method, you may still want to add your own method in order to validate the value that the user has entered, for example. Here is an example write-cell-value method that could be used with an editable-text-column-mixin column to allow the user to enter only integers.
(defmethod write-cell-value ((row my-grid-row)(column my-grid-column)
row-number column-number value)
;; Read a Lisp object from the text that the user typed.
;; Alternately you could use a data-write-converter function
;; to convert the string.
(let* ((object (ignore-errors (read-from-string value))))
;; Make sure that the object is an integer.
(if* (integerp object)
;; Don't bother to write the integer to the master data
;; if it's equal to the current value.
then (unless (= object
(read-cell-value row column
row-number column-number))
;; Call the default write-cell-value method, which
;; will call this column's data-writer function on
;; this row's data-object.
(call-next-method row column row-number column-number
;; Pass the converted value explicitly
;; if you didn't use a
;; data-write-converter function.
object))
else (pop-up-message-dialog
nil "Invalid Value" "The value must be an integer."
warning-icon "~OK"))))The row-number and column-number arguments are new to version 6.2. Applications that define methods on this generic function must add the new parameters to the method definitions. And any application calls to this generic function must pass the new arguments (just pass zeros to retain the old behavior). See the new example on the Examples tab of the Navigator dialog called Grid-widget: a basic replicated editable-text column to see how to write a write-cell-value method that uses these handy new arguments.
See also read-cell-value and the description of the grid-widget.
Generic Function, cg package
Arguments: grid-widget
Calls the application's write-cell-value methods and data-writer functions for each delayed interactive edit that is being held by grid-widget (which must be a grid-widget). The held values are then cleared. An application typically would call this function just after it asks the user to confirm or reject current edits to the grid, and the user confirms them. See delay-write-cell-value.
The modified property of the grid-widget will be true when there are delayed values that have not yet been written.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the x-axis property of a plot-widget. The value may be set at creation time by passing the x-axis initarg to make-instance when creating a plot-widget, or any time later by calling (setf x-axis).
The x-axis of a plot-widget is the primary horizontal axis of the widget, and always lies along the bottom side of the plot. If a secondary horizontal axis is desired along the top side of a plot, then use the x-axis-2 property for that.
The value of the x-axis property should be an instance of the plot-value-axis class, and holds properties that determine how the axis is drawn and the range of values that it displays. The properties are inherited from the value-axis and chart-axis classes.
The value of this property will always be a plot-value-axis instance. If you do not pass a plot-value-axis instance as the value of the x-axis initarg when creating a plot-widget, then a default instance is created automatically.
If there are multiple chart objects (see chart-objects), then some of the objects may use this axis for their x coordinates while others use the x-axis-2 axis.
See also x-axis-2, y-axis, y-axis-2, and plot-widget.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the x-axis-2 property of a plot-widget. The value may be set at creation time by passing the x-axis-2 initarg to make-instance when creating a plot-widget, or any time later by calling (setf x-axis-2).
The x-axis-2 of a plot-widget is an optional secondary horizontal axis of the widget, and lies along the top side of the plot. This axis will be drawn only when one or more of the chart objects are explicitly associated with this secondary axis in the chart-objects property.
The value of the x-axis-2 property should be an instance of the plot-value-axis class, and holds properties that determine how the axis is drawn and the range of values that it displays. The properties are inherited from the value-axis and chart-axis classes.
The value of this property will always be a plot-value-axis instance. If you do not pass a plot-value-axis instance as the value of the x-axis-2 initarg when creating a plot-widget, then a default instance is created automatically, even though it may never be drawn.
See also x-axis, y-axis, y-axis-2, and plot-widget.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the y-axis property of a plot-widget. The value may be set at creation time by passing the y-axis initarg to make-instance when creating a plot-widget, or any time later by calling (setf y-axis).
The y-axis of a plot-widget is the primary vertical axis of the widget, and always lies along the left side of the plot. If a secondary vertical axis is desired along the right side of a plot, then use the y-axis-2 property for that.
The value of the y-axis property should be an instance of the plot-value-axis class, and holds properties that determine how the axis is drawn and the range of values that it displays. The properties are inherited from the value-axis and chart-axis classes.
The value of this property will always be a plot-value-axis instance. If you do not pass a plot-value-axis instance as the value of the y-axis initarg when creating a plot-widget, then a default instance is created automatically.
If there are multiple chart objects (see chart-objects), then some of the objects may use this axis for their y coordinates while others use the y-axis-2 axis.
See also x-axis, x-axis-2, y-axis-2, and plot-widget.
Generic Function, cg package
Arguments: plot-widget
Returns the value of the y-axis-2 property of a plot-widget. The value may be set at creation time by passing the y-axis-2 initarg to make-instance when creating a plot-widget, or any time later by calling (setf y-axis-2).
The y-axis-2 of a plot-widget is an optional secondary vertical axis of the widget, and lies along the right side of the plot. This axis will be drawn only when one or more of the chart objects are explicitly associated with this secondary axis in the chart-objects property.
The value of the y-axis-2 property should be an instance of the plot-value-axis class, and holds properties that determine how the axis is drawn and the range of values that it displays. The properties are inherited from the value-axis and chart-axis classes.
The value of this property will always be a plot-value-axis instance. If you do not pass a plot-value-axis instance as the value of the y-axis-2 initarg when creating a plot-widget, then a default instance is created automatically, even though it may never be drawn.
See also x-axis, x-axis-2, y-axis, and plot-widget.
Function, cg package
Arguments: &optional format-string &rest args
Implements a y-or-n-p prompt by popping up a modal dialog with Yes and No buttons. format-string and args are printed (as if with format) in the dialog, typically explaining what choice the user is making. t is returned if the user clicks Yes, nil if the user clicks No.
The position of the dialog when displayed is controlled by position-utility-dialog.
See also yes-no-or-cancel-list.
Function, cg package
Arguments: title choice-list &key stream allow-multiple initial-value select-all on-print on-change width height dialog-exterior-box topmost
Displays a dialog with Yes, No, and Cancel buttons and a single or multiple item list widget. Two values are returned, the selected value (or the list of selected values if allow-multiple is true) and :yes or :no or nil as Yes, No, or Cancel is clicked. (Clicking the close box on the dialog is equivalent to clicking Cancel.)
The required arguments are title, which must be a string or nil and provides the title of the dialog (no title for nil), and choice-list, which must be a list. The items of choice-list will be displayed in the list widget on the dialog.
The keyword arguments are:
stream: this argument specifies the owning window. It defaults to the stream returned by selected-window-or-screen.
allow-multiple: if this argument is true, more than one item in choice-list can be chosen (using the Shift and Control keys in the usual Windows way). If select-all and allow-multiple are true, all items are selected when the dialog is displayed. (select-all is ignored if allow-multiple is not true.)
initial-value: the value should be a value from choice-list. It will be highlighted when the dialog is displayed. It effectively defaults to the first item of choice-list.
on-print: if specified, the value should be a function of one argument that will print the item in choice-list to the dialog.
on-change: the value may be either nil or a function or function name. If true, it is used as the on-change event handler for the item-list of the yes-no-or-cancel-list dialog. The function will therefore be called as the user highlights each choice in the dialog. This may be handy for showing a help message for each choice. The function should take the three arguments widget, new-value, and old-value (as usual with an on-change handler), and should always return true (since returning nil would prevent the user from successfully selecting a choice). The default value of on-change is nil, which causes an internal on-change handler to be used.
width and height: these arguments determine the width and height of the dialog displayed. The positioning of the dialog is determined, then, by position-utility-dialog. width and height should not be specified if dialog-exterior-box is specified, but use of dialog-exterior-box is deprecated in favor of width and height.
dialog-exterior-box: if a value is specified for this argument, it should be a box (see make-box). The dialog will be the size of the box specified but the location will be specified by position-utility-dialog (thus the top and left of the box are ignored). But, as noted above, the use of dialog-exterior-box is deprecated in favor of the width and height arguments. If values are specified for width and height, no value should be specified for dialog-exterior-box.
topmost: when true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application.
See also y-or-n-dialog and ask-user-for-choice-from-list.
Function, cg package
Arguments: window &optional new-state
Changes the state of window to new-state, which must be one of nil (the default), :maximized, or :normal. nil means toggle between :normal and :maximized.
This operator is now a non-generic function. It calls (setf state), which is a generic function to effect the change in its argument's state. If you added methods to this operator, you should modify them to be methods on (setf state). (See expand-window for an example.)
Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.
|
Allegro CL version 11.0 | ||||||||