Mercurial > hg > xemacs-beta

comparison man/widget.texi @ 1339:ffa6c90799b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2003-03-03 15:00:11 by stephent] Lisp widget docs <87bs0s33b7.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Mon, 03 Mar 2003 15:00:12 +0000
parents c1553814932e
children 8d350b095c21
comparison
equal deleted inserted replaced
1338:314c4e18dda0 1339:ffa6c90799b1
1388 Using @code{define-widget} just stores the definition of the widget type 1388 Using @code{define-widget} just stores the definition of the widget type
1389 in the @code{widget-type} property of @var{name}, which is what 1389 in the @code{widget-type} property of @var{name}, which is what
1390 @code{widget-create} uses. 1390 @code{widget-create} uses.
1391 1391
1392 If you just want to specify defaults for keywords with no complex 1392 If you just want to specify defaults for keywords with no complex
1393 conversions, you can use @code{identity} as your conversion function. 1393 conversions, you can use @code{identity} as your @code{:convert-widget}
1394 function.
1394 1395
1395 The following additional keyword arguments are useful when defining new 1396 The following additional keyword arguments are useful when defining new
1396 widgets: 1397 widgets:
1397 @table @code 1398 @table @code
1398 @item :convert-widget 1399 @item :convert-widget
1399 Function to convert a widget type before creating a widget of that 1400 Method to convert type-specific components of a widget type before
1400 type. It takes a widget type as an argument, and returns the converted 1401 instantiating a widget of that type. Not normally called from user
1401 widget type. When a widget is created, this function is called for the 1402 code, it is invoked by @code{widget-convert}. Typical operations
1402 widget type and all the widget's parent types, most derived first. 1403 include converting types of child widgets to widget instances and
1404 converting values from external format (@emph{i.e.}, as expected by the
1405 calling code) to internal format (which is often different for the
1406 convenience of widget manipulation). It takes a widget type as an
1407 argument, and returns the converted widget type. When a widget is
1408 created, the value of this property is called for the widget type, then
1409 for all the widget's parent types, most derived first. (The property is
1410 reevaluated for each parent type.)
1403 1411
1404 The following predefined functions can be used here: 1412 The following predefined functions can be used here:
1405 1413
1406 @defun widget-types-convert-widget widget 1414 @defun widget-types-convert-widget widget
1407 Convert @code{:args} as widget types in @var{widget}. 1415 Convert each member of @code{:args} in @var{widget} from a widget type
1416 to a widget.
1408 @end defun 1417 @end defun
1409 1418
1410 @defun widget-value-convert-widget widget 1419 @defun widget-value-convert-widget widget
1411 Initialize @code{:value} from @code{:args} in @var{widget}. 1420 Initialize @code{:value} from @code{(car :args)} in @var{widget}, and
1412 @end defun 1421 reset @code{:args}.
1422 @end defun
1423
1424 @item :copy
1425 A method to implement deep copying of the type. Any member of the
1426 widget which might be changed in place (rather than replaced) should be
1427 copied by this method. (@code{widget-copy} uses @code{copy-sequence} to
1428 ensure that the top-level list is a copy.) This particularly applies to
1429 child widgets.
1413 1430
1414 @item :value-to-internal 1431 @item :value-to-internal
1415 Function to convert the value to the internal format. The function 1432 Function to convert the value to the internal format. The function
1416 takes two arguments, a widget and an external value. It returns the 1433 takes two arguments, a widget and an external value. It returns the
1417 internal value. The function is called on the present @code{:value} 1434 internal value. The function is called on the present @code{:value}
1425 when the widget is created, and on any value set later with 1442 when the widget is created, and on any value set later with
1426 @code{widget-value-set}. 1443 @code{widget-value-set}.
1427 1444
1428 @item :create 1445 @item :create
1429 Function to create a widget from scratch. The function takes one 1446 Function to create a widget from scratch. The function takes one
1430 argument, a widget type, and creates a widget of that type, inserts it 1447 argument, a widget, and inserts it in the buffer. Not normally called
1431 in the buffer, and returns a widget object. 1448 from user code. Instead, call @code{widget-create} or related
1449 functions, which take a type argument, (usually) convert it to a widget,
1450 call the @code{:create} function to insert it in the buffer, and then
1451 return the (possibly converted) widget.
1452
1453 The default, @code{widget-default-create}, is invariably appropriate.
1454 (None of the standard widgets specify @code{:create}.)
1432 1455
1433 @item :delete 1456 @item :delete
1434 Function to delete a widget. The function takes one argument, a widget, 1457 Function to delete a widget. The function takes one argument, a widget,
1435 and should remove all traces of the widget from the buffer. 1458 and should remove all traces of the widget from the buffer.
1436 1459
1501 1524
1502 It provides most of the functionality that is referred to as ``by 1525 It provides most of the functionality that is referred to as ``by
1503 default'' in this text. 1526 default'' in this text.
1504 @end deffn 1527 @end deffn
1505 1528
1529 In implementing complex hierarchical widgets (@emph{e.g.}, using the
1530 @samp{group} widget), the following functions may be useful.
1531 The syntax for the @var{type} arguments to these functions is described
1532 in @ref{Basic Types}.
1533
1534 @defun widget-create-child-and-convert parent type &rest args
1535 As a child of @var{parent}, create a widget with type @var{type} and
1536 value @var{value}. @type{type} is copied, and the @code{:widget-contvert}
1537 method is applied to the optional keyword arguments from @var{args}.
1538 @end defun
1539
1540 @defun widget-create-child parent type
1541 As a child of @var{parent}, create a widget with type @var{type}.
1542 @type{type} is copied, but no conversion method is applied.
1543 @end defun
1544
1545 @defun widget-create-child-value parent type value
1546 As a child of @var{parent}, create a widget with type @var{type} and
1547 value @var{value}. @type{type} is copied, but no conversion method is
1548 applied.
1549 @end defun
1550
1551 @defun widget-convert type &rest args
1552 Convert @var{type} to a widget without inserting it in the buffer.
1553 The optional @var{args} are additional keyword arguments.
1554
1555 The widget's @code{:args} property is set from the longest tail of
1556 @var{args} whose @samp{cdr} is not a keyword, or if that is null, from
1557 the longest tail of @var{type}'s @code{:args} property whose cdr is not
1558 a keyword. Keyword arguments from @var{args} are set, and the
1559 @code{:value} property (if any) is converted from external to internal
1560 format.
1561 @end defun
1562
1563 @code{widget-convert} is typically not called from user code; rather it
1564 is called implicitly through the @samp{widget-create*} functions.
1565
1506 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top 1566 @node Widget Browser, Widget Minor Mode, Defining New Widgets, Top
1507 @comment node-name, next, previous, up 1567 @comment node-name, next, previous, up
1508 @section Widget Browser 1568 @section Widget Browser
1509 1569
1510 There is a separate package to browse widgets. This is intended to help 1570 There is a separate package to browse widgets. This is intended to help