source: trunk/third/oaf/docs/standard-attributes.txt @ 15904

Revision 15904, 7.5 KB checked in by ghudson, 24 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r15903, which included commits to RCS files with non-trunk default branches.
Line 
1
2
3Standard .oafinfo file attributes.
4
5Not all components must specify all of these, but if they are present
6they ought to have these standardized meanings. A component should
7specify at least "repo_ids", "name" and "description" to be useful.
8
9Other attributes should be placed in a colon-separated namespace.
10
11
12General
13
14* "repo_ids" (stringv) - all the IDL interfaces this component
15  implements, including inherited interfaces. If Bonobo::Unknown is
16  one of the interfaces, this should include all interfaces that can
17  be query_interface()d for.  Fake interfaces like
18  IDL:BonoboControl/text-plain:1.0 should _not_ be included. If this
19  attribute is omitted, the object will be assuemd to support no IDL
20  interfaces, which makes no sense.
21
22* "description" (string) - a free text description of the component,
23  much like the gnorba description field. If omitted, the "name"
24  attribute will be used, if present, otherwise the empty string.
25
26* "name" (string) - a short name suitable for display to the end user,
27  e.g. in a menu. If omitted, the "description" attribute will be
28  used, if present, otherwise the iid.
29
30
31Bonobo
32
33* "bonobo:editable" (boolean) - does this component allow editing of
34  its contents? If omitted, assumed false or not applicable.
35
36* "bonobo:supported_mime_types" (stringv) - a list of mime types this
37  component understands as input. In addition to specific mime types,
38  it is possible to include supertypes (e.g. "image/*" or "text/*") or
39  "*/*" to indicate the component can display any mime
40  type. Specifying "*/*" is only necessary if "supported_uri_schemes"
41  is not specified, otherwise it is assumed. This only really makes
42  sense if the component implements one of the following interfaces:
43  Bonobo::PersistStream, Bonobo::ProgressiveDataSink, Nautilus::View.
44
45* "bonobo:supported_uri_schemes" (stringv) - a list of protocols this
46  component knows how to handle. This only really makes sense if the
47  component implements one of the following interfaces:
48  Bonobo::PersistFile or Nautilus::View
49
50  If "bonobo:supported_uri_schemes" is specified but
51"bonobo:supported_mime_types" is not, it is assumed the component can
52handle any type of data that might come via that protocol. Some
53schemes may not even have an associated mime type for any given URI,
54for instance irc: or news:
55
56  If "bonobo:supported_mime_types" is specified but
57"bonobo:supported_uri_schemes" is not, the component is assumed to be
58able to handle all common URI schemes (possible definition: anything
59gnome-vfs can handle).
60
61  If neither "bonobo:supported_uri_schemes" nor
62"bonobo:supported_mime_types" is specified, it is assumed the
63component cannot handle any data at all in a general way and should
64never be generically selected for such purposes.
65
66
67Nautilus - Content Views
68
69* "nautilus:view_as_name" (string) - a suitable name for use as a view
70as name (it will be displayed as "View as <foo>" where <foo> is the
71name). This must be implemented by any Bonobo Embeddables
72or Controls that can be used as Nautilus views (for the content in
73the main window, not in the sidebar).
74
75* "nautilus:view_as_label" (string) - A string generally of the form
76"View as <view_as_name>". This is easier for translators to handle
77than composed strings. It also allows changes to that text, like "View
78with <foo>" rather than "View as <foo>".
79
80* "nautilus:viewer_label" (string) - A string generally of the form
81"<view_as_name> Viewer". This is easier for translators to handle
82than composed strings.
83
84
85I am not totally sure if the following two should be in the nautilus:
86or bonobo: namespace; I can see them being useful for other components
87at least in theory. Leaving as "nautilus:" attributes for now.
88
89* "nautilus:required_directory_content_mime_types" (stringv) - if the
90component is to be activated on a URI with mime type
91special/directory, it is only really applicable if the directory
92contains one of these mime types. As before, supertypes like "audio/*"
93are allowed. If this attribute is omitted, "*/*" is assumed.
94
95* "nautilus:required_uri_tester" (string) - this specifies the OAFIID
96of a component that implements the Nautilus::URITester interface (see
97proposal below). If the criteria established by all the other
98attributes are satisfied, an object with that OAFIID should be
99activated and its is_applicable() method should be called on the URI
100to test if it this component _really_, _really_ applies to the given
101URI. This should be used as a last resort. (Not yet implemented.)
102
103The reason for the "required_uri_tester" attribute is as follows. In
104Nautilus, we plan to have custom directory views that express
105higher-level semantics about certain directories, but that depend
106heavily on the directory contents. For example, there maybe "View as
107Version Controlled Directory" or the like which depends on their being
108a directory named "CVS/" in the appropriate directory. So in the most
109general case, we need to run some code specific to the component to
110make sure it is applicable to a given URI. Now, we could just activate
111the component, require it to have the URITester interface, do the
112test, and then destroy it to find out if it applies. But that might be
113quite heavyweight. So intead we specify the OAFIID of a different
114component, one which could be very lightweight (shlib or minimal exe
115that does not pull gnome/gtk stuff) which does the test and nothing
116else.
117
118If this attribute is not provided, no such testing is assumed
119necessary.
120
121
122Nautilus - Sidebar Views:
123
124* "nautilus:sidebar_panel_name" (string) - a suitable name for use as
125a sidebar panel label name. This must be implemented by any Bonobo
126Controls that can be used as a Nautilus sidebar view.
127
128* "nautilus:recommended_uri_schemes" (string) - the URI schemes this
129meta view is most recommended for. If "*" is included, this component
130is recommended for all schemes. If omitted or empty, it is not
131recommended for any. (Not yet implemented.)
132
133
134Vertigo:
135
136* "vertigo:category" - the name of the category a panel applet falls
137  into, for purposes of generating the menu.
138
139
140General open questions
141
142* How does Bonobo::PersistStorage play into this?
143
144* An "icon" attribute has been proposed for component browser/selector
145  purposes. If included it would have to be inline probably
146  (base64-encoded png?) since the oafinfo file may not be on the same
147  machine as the code doing the browsing or activation.
148
149* How to specify interesting info about applicable components when
150  there is no relevant URI? For instance a regular dumb control, or
151  something like the gnomines control where there is no relevant
152  type. Maybe you only ever want to pick these off a list or activate
153  a specific one by IID. Maybe controls that want to be activatable in
154  nautilus somehow can just register their own URI scheme, for
155  instance `gnome-control-mines:' for the gnomines thing. This seems
156  like kind of a hack though.
157
158* Should "description" and the various name attributes be
159  internationalized? If so, how? should there be other attributes with
160  names like "description_${LANG}"? Someone proposed using
161  lang="de"/lang="ru" in the XML tag.
162
163Nautilus-specific open questions
164
165* Should there be a way to use a Bonobo Control or Embeddable with
166  Nautilus without requiring the developer to include a definition
167  for "nautilus:sidebar_panel_name" or "nautilus:view_as_name"?
168
169* Should the user level of a component be an attribute? That lets just
170  any component author set the user level instead of centralizing it.
171
172==================
173
174module Nautilus {
175        interface URITester {
176                boolean is_applicable (string uri);
177        }
178}
Note: See TracBrowser for help on using the repository browser.