2
* @OPENGROUP_COPYRIGHT@
4
* Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.
5
* Copyright (c) 1996, 1997, 1998, 1999, 2000 The Open Group
6
* ALL RIGHTS RESERVED (MOTIF). See the file named COPYRIGHT.MOTIF for
7
* the full copyright text.
9
* This software is subject to an open license. It may only be
10
* used on, with or for operating systems which are themselves open
11
* source systems. You must contact The Open Group for a license
12
* allowing distribution and sublicensing of this software on, with,
13
* or for operating systems which are not Open Source programs.
15
* See http://www.opengroup.org/openmotif/license for full
16
* details of the license agreement. Any use, reproduction, or
17
* distribution of the program constitutes recipient's acceptance of
20
* EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS
21
* PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
22
* KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY
23
* WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY
24
* OR FITNESS FOR A PARTICULAR PURPOSE
26
* EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT
27
* NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT,
28
* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29
* DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED
30
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
32
* ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
33
* EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE
34
* POSSIBILITY OF SUCH DAMAGES.
46
static char rcsid[] = "$XConsortium: Mrmappl.c /main/17 1996/11/13 13:59:58 drk $"
51
* (c) Copyright 1996 Hewlett-Packard Company *
52
* (c) Copyright 1996 International Business Machines Corp. *
53
* (c) Copyright 1996 Sun Microsystems, Inc. *
54
* (c) Copyright 1996 Novell, Inc. *
55
* (c) Copyright 1989, 1990, 1996 Digital Equipment Corporation. *
56
* (c) Copyright 1996 FUJITSU LIMITED. *
57
* (c) Copyright 1996 Hitachi. *
64
* UIL Resource Manager (URM):
68
* These are the top-level routines in URM normally accessible to
69
* and used by an application at runtime to access URM facilities.
81
#include <Mrm/MrmAppl.h>
90
* MrmOpenHierarchy Open a hierarchy
92
* MrmOpenHierarchyPerDisplay Open a hierarchy taking display arg
94
* MrmOpenHierarchyFromBuffer Open a hierarchy from a memory buffer
96
* MrmCloseHierarchy Close an open hierarchy
98
* MrmRegisterClass Register a widget class
100
* MrmFetchInterfaceModule Fetch widgets in an interface module
102
* MrmFetchWidget Fetch a widget
104
* MrmFetchWidgetOverride Fetch a widget, overriding name, args
106
* MrmFetchSetValues Do SetValues from UID literals
115
* PROCEDURE DESCRIPTION:
117
* This routine allocates a hierarchy descriptor, and opens
118
* all the IDB files in the hierarchy. It initializes the
119
* optimized search lists in the hierarchy from the open files.
120
* All files are closed if there are any errors.
124
* num_files The number of files in the name list
125
* name_list A list of the file names
126
* os_ext_list A list of system-dependent ancillary
127
* structures corresponding to the files.
128
* This parameter may be NULL.
129
* hierarchy_id_return To return the hierarchy id
137
* MrmSUCCESS operation succeeded
138
* MrmFAILURE operation failed, no further reason
139
* Others see UrmIdbOpenFileRead
148
#if NeedWidePrototypes
154
MrmOsOpenParamPtr *os_ext_list,
155
MrmHierarchy *hierarchy_id_return)
164
result = Urm__OpenHierarchy
165
(num_files, name_list, os_ext_list, hierarchy_id_return, FALSE, NULL);
175
* PROCEDURE DESCRIPTION:
177
* This routine allocates a hierarchy descriptor, and opens
178
* all the IDB files in the hierarchy. It initializes the
179
* optimized search lists in the hierarchy from the open files.
180
* All files are closed if there are any errors.
184
* display The Display to be passed to XtResolvePathname
185
* num_files The number of files in the name list
186
* name_list A list of the file names
187
* os_ext_list A list of system-dependent ancillary
188
* structures corresponding to the files.
189
* This parameter may be NULL.
190
* hierarchy_id_return To return the hierarchy id
198
* MrmSUCCESS operation succeeded
199
* MrmFAILURE operation failed, no further reason
200
* Others see UrmIdbOpenFileRead
208
MrmOpenHierarchyPerDisplay (Display *display,
209
#if NeedWidePrototypes
215
MrmOsOpenParamPtr *os_ext_list,
216
MrmHierarchy *hierarchy_id_return)
222
MrmOsOpenParam os_data;
223
MrmOsOpenParamPtr new_os_ext_list = &os_data;
228
if (os_ext_list == NULL)
229
os_ext_list = (MrmOsOpenParamPtr *)&new_os_ext_list;
231
(*os_ext_list)->display = display;
233
result = Urm__OpenHierarchy(num_files, name_list, os_ext_list,
234
hierarchy_id_return, FALSE, NULL);
244
* PROCEDURE DESCRIPTION:
246
* MrmOpenHierarcyFromBuffer opens a buffer containing the
247
* memory image of a UID file.
251
* hierarchy_id ID of an open URM database hierarchy
260
* MrmSUCCESS operation succeeded
261
* MrmFAILURE operation failed, no further reason
269
MrmOpenHierarchyFromBuffer (unsigned char *uid_buffer,
270
MrmHierarchy *hierarchy_id_return)
279
result = Urm__OpenHierarchy((MrmCount) 1, NULL, NULL,
280
hierarchy_id_return, TRUE, uid_buffer);
288
* PROCEDURE DESCRIPTION:
290
* MrmCloseHierarchy closes a URM search hierarchy.
294
* hierarchy_id ID of an open URM database hierarchy
303
* MrmSUCCESS operation succeeded
304
* MrmFAILURE operation failed, no further reason
312
MrmCloseHierarchy (MrmHierarchy hierarchy_id)
321
result = Urm__CloseHierarchy (hierarchy_id);
331
* PROCEDURE DESCRIPTION:
333
* This routine registers a vector of names and associated values
334
* for access in URM. The values may be callback routines, pointers
335
* to user-defined data, or any other values. The information provided
336
* is used exactly as registered callback information is used.
338
* The names in the list are case-sensitive, as usual. The list may
339
* either ordered or unordered; this routine will detect lexicographic
340
* ordering if it exists, and exploit it.
342
* For details on callbacks in URM, consult XmRegisterMRMCallbacks.
346
* reglist A list of name/value pairs for the names to
347
* be registered. Each name is a case-sensitive
348
* nul-terminated ASCII string. Each value is
349
* a 32-bit quantity, interpreted as a procedure
350
* address if the name is a callback routine, and
351
* uninterpreted otherwise.
352
* num_reg The number of entries in reglist.
366
MrmRegisterNames (MrmRegisterArglist reglist,
367
#if NeedWidePrototypes
378
Cardinal result; /* function result */
379
String *names; /* vector of names */
380
XtPointer *values; /* vector of values */
381
int ndx; /* loop index */
386
* Construct RegisterNames vectors, and call the WCI routine
388
names = (String *) XtMalloc (num_reg*sizeof(String));
389
values = (XtPointer *) XtMalloc (num_reg*sizeof(XtPointer));
390
for ( ndx=0 ; ndx<num_reg ; ndx++ )
392
names[ndx] = reglist[ndx].name;
393
values[ndx] = reglist[ndx].value;
396
result = Urm__WCI_RegisterNames (names, values, num_reg);
397
XtFree ((char*)names);
398
XtFree ((char*)values);
409
* PROCEDURE DESCRIPTION:
411
* This routine registers a vector of names and associated values for
412
* access in URM within a specific hierarchy. It is similar to
413
* MrmRegisterNames, except that the names have scope only over the
414
* hierarchy rather than global scope. For information on the names
415
* and values, see MrmRegister Names.
419
* hierarchy_id An open hierarchy descriptor.
420
* reglist A list of name/value pairs for the names to
421
* be registered. Each name is a case-sensitive
422
* nul-terminated ASCII string. Each value is
423
* a 32-bit quantity, interpreted as a procedure
424
* address if the name is a callback routine, and
425
* uninterpreted otherwise.
426
* num_reg The number of entries in reglist.
440
MrmRegisterNamesInHierarchy (MrmHierarchy hierarchy_id,
441
MrmRegisterArglist reglist,
442
#if NeedWidePrototypes
453
Cardinal result; /* function result */
454
String *names; /* vector of names */
455
XtPointer *values; /* vector of values */
456
int ndx; /* loop index */
460
* Construct RegisterNames vectors, and call the hierarchy routine
462
names = (String *) XtMalloc (num_reg*sizeof(String));
463
values = (XtPointer *) XtMalloc (num_reg*sizeof(XtPointer));
464
for ( ndx=0 ; ndx<num_reg ; ndx++ )
466
names[ndx] = reglist[ndx].name;
467
values[ndx] = reglist[ndx].value;
470
result = Urm__RegisterNamesInHierarchy
471
(hierarchy_id, names, values, num_reg);
472
XtFree ((char*)names);
473
XtFree ((char*)values);
484
* PROCEDURE DESCRIPTION:
486
* MrmFetchInterfaceModule fetches all the widgets defined in some
487
* interface module in the URM database hierarchy. Typically, each
488
* application has one or more modules which define its interface;
489
* each must be fetched in order to initialize all the widgets the
490
* application requires. Applications are not constrained to have all
491
* their widgets defined in a single module.
493
* If the module defines a main window widget, MrmFetchInterfaceModule
494
* returns its id. If no main window widget is contained in the module,
495
* NULL is returned. No widgets are realized. The ids of widgets other
496
* than the main window may be obtained using creation callbacks.
500
* hierarchy_id Hierarchy containing interface definition
501
* module_name Name of interface module defining top level of
502
* interface; by convention, this is usually the generic
503
* name of the application
504
* parent The parent widget for the topmost widgets being
505
* fetched from the module. Usually the top-level
507
* w_return To return the widget id of the main window widget
508
* for the application
516
* MrmSUCCESS operation succeeded
517
* MrmNOT_FOUND interface module or topmost widget not found
518
* MrmFAILURE Couldn't complete initialization
527
MrmFetchInterfaceModule (MrmHierarchy hierarchy_id,
530
Widget *w_return) /* unused */
537
Cardinal result; /* function results */
538
URMResourceContextPtr mod_context; /* context containing module */
539
RGMModuleDescPtr modptr; /* Interface module in context */
540
int ndx; /* loop index */
541
Widget cur_w; /* current widget id */
542
MrmType class; /* current widget class */
543
IDBFile hfile_id; /* file where module was found */
544
_MrmWidgetToAppContext(parent);
549
* Validate the hierachy, then attempt to fetch the module.
551
if ( hierarchy_id == NULL )
553
result = Urm__UT_Error ("MrmFetchInterfaceModule", _MrmMMsg_0023,
554
NULL, NULL, MrmBAD_HIERARCHY);
560
if ( ! MrmHierarchyValid(hierarchy_id) )
562
result = Urm__UT_Error ("MrmFetchInterfaceModule", _MrmMMsg_0024,
563
NULL, NULL, MrmBAD_HIERARCHY);
569
result = UrmGetResourceContext (NULL, NULL, 0, &mod_context);
570
if ( result != MrmSUCCESS )
577
result = UrmIFMHGetModule (hierarchy_id, module_name, mod_context, &hfile_id);
578
if ( result != MrmSUCCESS )
580
UrmFreeResourceContext (mod_context);
587
* We have the module. Loop through all the widgets it defines, and fetch
590
modptr = (RGMModuleDescPtr) UrmRCBuffer (mod_context);
591
if ( ! UrmInterfaceModuleValid(modptr) )
593
UrmFreeResourceContext (mod_context);
594
result = Urm__UT_Error ("MrmFetchInterfaceModule", _MrmMMsg_0025,
595
NULL, mod_context, MrmBAD_IF_MODULE);
601
for ( ndx=0 ; ndx<modptr->count ; ndx++ )
603
result = MrmFetchWidget (hierarchy_id, modptr->topmost[ndx].index,
604
parent, &cur_w, &class);
605
if ( result != MrmSUCCESS )
607
UrmFreeResourceContext (mod_context);
615
* successfully fetched all widgets
617
UrmFreeResourceContext (mod_context);
629
* PROCEDURE DESCRIPTION:
631
* MrmFetchWidget fetchs any indexed application widget. As usual in fetch
632
* operations, the fetched widget's subtree is also fetched. There are
633
* no constraints on this widget except that it must not also appear
634
* as the child of some widget within its own subtree, i.e. there must
635
* be no cycles in the subtree graph! MrmFetchWidget does not do a
636
* XtManageChild for the newly created widget.
638
* The semantics of the URM database require that any widget which is to
639
* be fetched with MrmFetchWidget meet the following requirements:
641
* o Not be referenced as the child of any widget in the database
645
* MrmFetchWidget replaces XmFetchTopmost, and is used to fetch
646
* topmost widgets where MrmFetchInterfaceModule is not used. A topmost
647
* widget is either the main window or any indexed widget whose parent is
648
* the top-level widget. MrmFetchWidget may be called at any time to fetch
649
* a widget which was not fetched at application startup. MrmFetchWidget
650
* determines if a widget has already been fetched by checking *w_return
651
* for a NULL value. Non-NULL values signify that the widget already
652
* has been fetched, and MrmFetchWidget no-ops. (If the toolkit ever
653
* supplies a validation routine for widgets, this will be used in
654
* place of a non-NULL check). Thus MrmFetchWidget may be used to
655
* defer fetching popup widgets until they are first referenced
656
* (presumably in a callback), and then fetching them once.
658
* MrmFetchWidget may also be used to make multiple instances of a
659
* widget (and its subtree). In this case, the UID definition functions
660
* as a skeleton; there are no constraints on how many times a widget
661
* definition may be fetched. The only requirement is the *w_return be
662
* NULL on each call. This may be used to make multiple copies of
663
* a widget in e.g. a dialog box or menu (to construct a uniform form).
665
* The index which identifies the widget must be known to the application
666
* via previous agreement.
667
* MrmFetchWidget will successfully fetch topmost widgets as long as the
668
* parent parameter is correct (the top-level widget), and this
669
* replaces XmFetchTopmost (which vanishes).
673
* hierarchy_id Hierarchy containing interface definition
674
* index The index of the widget to fetch.
675
* parent ID of the parent widget
676
* w_return To return the widget id of the created widget.
677
* *w_return must be NULL or MrmFetchWidget no-ops.
678
* class_return To return the code identifying the widget class.
679
* This is principally used to distinguish main window
680
* and other toolkit widgets. It will be one of the
681
* URMwc... codes defined in MRM.h. The code
682
* for a main window is URMwcMainWindow.
690
* MrmSUCCESS operation succeeded
691
* MrmNOT_FOUND widget not found in database
692
* MrmFAILURE operation failed, no further reason
700
MrmFetchWidget (MrmHierarchy hierarchy_id,
704
MrmType *class_return)
707
return MrmFetchWidgetOverride (hierarchy_id, index, parent,
708
NULL, NULL, 0, w_return, class_return);
717
* PROCEDURE DESCRIPTION:
719
* This procedure is the extended version of MrmFetchWidget. It is
720
* identical to MrmFetchWidget in all respsects, except that it allows
721
* the caller to override the widget's name and any number of the
722
* arguments which would otherwise receive from the UID database or
723
* one of the defaulting mechanisms (i.e. the override is not limited
724
* to those arguments in the UID file).
726
* The override parameters apply only to the widget fetched and returned
727
* by this procedure; its children (subtree) do not receive any override
732
* hierarchy_id Hierarchy containing interface definition
733
* index The index of the widget to fetch.
734
* parent ID of the parent widget
735
* ov_name Name to override widget name (NULL for no override)
736
* ov_args Override arglist, exactly as would be given to
737
* XtCreateWidget (conversion complete, etc). NULL
739
* ov_num_args # args in ov_args; 0 for no override
740
* w_return To return the widget id of the created widget.
741
* *w_return must be NULL or MrmFetchWidget no-ops.
742
* class_return To return the code identifying the widget class.
743
* This is principally used to distinguish main window
744
* and other toolkit widgets. It will be one of the
745
* URMwc... codes defined in MRM.h. The code
746
* for a main window is URMwcMainWindow.
754
* MrmSUCCESS operation succeeded
755
* MrmNOT_FOUND widget not found in database
756
* MrmFAILURE operation failed, no further reason
764
MrmFetchWidgetOverride (MrmHierarchy hierarchy_id,
769
Cardinal ov_num_args,
771
MrmType *class_return)
777
Cardinal result; /* function results */
778
URMResourceContextPtr w_context; /* context containing widget */
779
RGMWidgetRecordPtr widgetrec; /* widget record in context */
780
IDBFile hfile_id; /* file in widget was found */
781
URMResourceContextPtr wref_ctx; /* for widget references */
782
URMSetValuesDescPtr svlist = NULL; /* list of SetValues descriptors */
783
int ndx ; /* loop index */
785
_MrmWidgetToAppContext(parent);
791
* Validate the hierachy, then attempt to fetch the widget
793
if ( hierarchy_id == NULL )
795
result = Urm__UT_Error ("MrmFetchWidgetOverride", _MrmMMsg_0023,
796
NULL, NULL, MrmBAD_HIERARCHY);
802
if ( ! MrmHierarchyValid(hierarchy_id) )
804
result = Urm__UT_Error ("MrmFetchWidgetOverride", _MrmMMsg_0024,
805
NULL, NULL, MrmBAD_HIERARCHY);
811
result = UrmGetResourceContext (NULL, NULL, 300, &w_context);
812
if ( result != MrmSUCCESS )
819
result = UrmHGetWidget (hierarchy_id, index, w_context, &hfile_id);
820
if ( result != MrmSUCCESS )
822
UrmFreeResourceContext (w_context);
829
* Validate the widget record, then set the class return. Then instantiate the
830
* widget and its subtree.
832
widgetrec = (RGMWidgetRecordPtr) UrmRCBuffer (w_context);
833
if ( ! UrmWRValid(widgetrec) )
835
UrmFreeResourceContext (w_context);
836
result = Urm__UT_Error ("MrmFetchWidgetOverride", _MrmMMsg_0026,
837
NULL, w_context, MrmFAILURE);
843
* The following test breaks compatibility with the CDE1.0
844
* version of Mrm and cannot be done for CDEnext.
846
* if (widgetrec->access == URMaPrivate)
848
* UrmFreeResourceContext (w_context);
849
* sprintf(errmsg, _MrmMMsg_0119, index);
850
* result = Urm__UT_Error("MrmFetchWidgetOverride", errmsg,
851
* NULL, w_context, MrmFAILURE);
852
* _MrmProcessUnlock();
853
* _MrmAppUnlock(app);
858
*class_return = widgetrec->type;
860
Urm__CW_InitWRef (&wref_ctx);
861
result = UrmCreateWidgetTree (w_context, parent, hierarchy_id, hfile_id,
862
ov_name, ov_args, ov_num_args,
863
URMrIndex, index, 0L, MrmManageDefault,
864
(URMPointerListPtr *)&svlist, wref_ctx,
866
UrmFreeResourceContext (w_context);
867
if ( result != MrmSUCCESS )
877
if ( svlist != NULL )
879
for ( ndx=0 ; ndx<UrmPlistNum((URMPointerListPtr)svlist) ; ndx++ )
880
Urm__CW_FreeSetValuesDesc
881
((URMSetValuesDescPtr)UrmPlistPtrN((URMPointerListPtr)svlist,ndx));
882
UrmPlistFree ((URMPointerListPtr)svlist);
884
UrmFreeResourceContext (wref_ctx);
887
* successfully initialized
900
* PROCEDURE DESCRIPTION:
902
* This routine does an XtSetValues on a widget, evaluating the values
903
* as public literal resource references resolvable from a URM
904
* hierarchy. Each literal is fetched from the hierarchy, and
905
* its value is fixed up and converted as required. This value is
906
* then placed in the arglist, and used as the actual value for
907
* an XtSetValues call. This routine allows a widget to be modified
908
* after creation using UID file values exactly as is done for creation
909
* values in MrmFetchWidget.
911
* As in FetchWidget, each argument whose value can be evaluated from
912
* the UID hierarchy is set in the widget. Values which are not found
913
* or for which conversion errors occur are not modified.
915
* Each entry in the arglist identifies an argument to be modified in
916
* the widget. The .name part identifies the tag, as usual (XmN...).
917
* the .value part must be a String whose values is the index of the
919
* args[n].name = "label" (XmNlabel)
920
* args[n].value = "OK_button_label"
921
* would modify the label resource of the widget to have the value
922
* of the literal accessed by index 'OK_button_label' in the
927
* hierarchy_id URM hierarchy to be searched for literal definitions
928
* w the widget to be modified
929
* args An arglist specifying the widget arguments to be
930
* modified. The .name part of each argument must be
931
* the usual XmN... string identifying the argument
932
* (argument tag). The .value part must be a String
933
* giveing the index of the literal. All literals must
934
* be public literals accessed by index.
935
* num_args the number of entries in args.
949
MrmFetchSetValues (MrmHierarchy hierarchy_id,
959
_MrmWidgetToAppContext(w);
965
* Validate the hierachy, then attempt to modify the widget
967
if ( hierarchy_id == NULL )
969
result = Urm__UT_Error ("MrmFetchSetValues", _MrmMMsg_0023,
970
NULL, NULL, MrmBAD_HIERARCHY);
976
if ( ! MrmHierarchyValid(hierarchy_id) )
978
result = Urm__UT_Error ("MrmFetchSetValues", _MrmMMsg_0024,
979
NULL, NULL, MrmBAD_HIERARCHY);
985
result = UrmFetchSetValues (hierarchy_id, w, args, num_args);