Line 38: |
Line 38: |
| If you're not already familiar with the [[OpenDoc]] human interface, you should | | If you're not already familiar with the [[OpenDoc]] human interface, you should |
| first read "[[The OpenDoc User Experience]]" in develop Issue 22 to get up to | | first read "[[The OpenDoc User Experience]]" in develop Issue 22 to get up to |
− | speed. This article also requires you to know something about OpenDoc storage | + | speed. This article also requires you to know something about [[OpenDoc]] storage |
| and how to use the ODStorageUnit class. "[[Getting Started With OpenDoc Storage]]" | | and how to use the ODStorageUnit class. "[[Getting Started With OpenDoc Storage]]" |
| in develop Issue 24 is a good introduction; further details can be found in the | | in develop Issue 24 is a good introduction; further details can be found in the |
Line 69: |
Line 69: |
| <p><li> Macintosh standards -- TEXT, PICT, stxt, MOOV, 3DMF</ul>Part kinds are | | <p><li> Macintosh standards -- TEXT, PICT, stxt, MOOV, 3DMF</ul>Part kinds are |
| usually specified as ISO strings (null-terminated ASCII strings using 7-bit | | usually specified as ISO strings (null-terminated ASCII strings using 7-bit |
− | characters) for manipulation by OpenDoc. As you can see from our list, standard | + | characters) for manipulation by [[OpenDoc]]. As you can see from our list, standard |
| Macintosh part kinds are actually today's standard Macintosh file types, except | | Macintosh part kinds are actually today's standard Macintosh file types, except |
| that instead of being file-type signatures they're ISO strings, which can be | | that instead of being file-type signatures they're ISO strings, which can be |
Line 99: |
Line 99: |
| text as part of its definition, such as PostScript, HTML, or BinHex. These data | | text as part of its definition, such as PostScript, HTML, or BinHex. These data |
| formats should be part kinds in their own right. Otherwise, there will be | | formats should be part kinds in their own right. Otherwise, there will be |
− | confusion when OpenDoc needs to find a substitute part editor for a part that | + | confusion when [[OpenDoc]] needs to find a substitute part editor for a part that |
| claims to be TEXT but is in fact another kind such as HTML. The user won't be | | claims to be TEXT but is in fact another kind such as HTML. The user won't be |
| happy with the result. <p> | | happy with the result. <p> |
| If you decide to use an industry-standard part kind, the Bento container suite | | If you decide to use an industry-standard part kind, the Bento container suite |
| (part of the storage system in OpenDoc 1.0) can help you solve internal | | (part of the storage system in OpenDoc 1.0) can help you solve internal |
− | byte-ordering problems and ensure that a document written on any OpenDoc | + | byte-ordering problems and ensure that a document written on any [[OpenDoc]] |
− | platform can be read and written on any other OpenDoc platform. However, your | + | platform can be read and written on any other [[OpenDoc]] platform. However, your |
| part editor is responsible for proper byte ordering of the values in the | | part editor is responsible for proper byte ordering of the values in the |
| content property of your storage unit. (Data formats typically specify byte | | content property of your storage unit. (Data formats typically specify byte |
− | ordering, so OpenDoc stays out of your way here.) The Standard Type I/O | + | ordering, so [[OpenDoc]] stays out of your way here.) The Standard Type I/O |
| utilities (see the file StdTypIO.h and the functions declared there) solve the | | utilities (see the file StdTypIO.h and the functions declared there) solve the |
| byte-ordering problem for a variety of simple data formats. These utilities can | | byte-ordering problem for a variety of simple data formats. These utilities can |
Line 132: |
Line 132: |
| </h4> | | </h4> |
| When a user tries to open a document or edit a part and the editor that created | | When a user tries to open a document or edit a part and the editor that created |
− | it is missing, OpenDoc searches for a substitute. This occurs as part of | + | it is missing, [[OpenDoc]] searches for a substitute. This occurs as part of |
− | OpenDoc's binding process -- the process of assigning the correct part editor | + | [[OpenDoc]]'s binding process -- the process of assigning the correct part editor |
− | to a given part. When a document is opened, the OpenDoc binding subsystem binds | + | to a given part. When a document is opened, the [[OpenDoc]] binding subsystem binds |
− | editors to all parts that need to be displayed. During execution, OpenDoc binds | + | editors to all parts that need to be displayed. During execution, [[OpenDoc]] binds |
| editors to part data when a part is read in or when its editor is explicitly | | editors to part data when a part is read in or when its editor is explicitly |
| changed. <p> | | changed. <p> |
Line 142: |
Line 142: |
| formats: a proprietary part kind (SurfWriter Text) and two standard part kinds | | formats: a proprietary part kind (SurfWriter Text) and two standard part kinds |
| (RTF and TEXT). And suppose that SurfWriter Text is the preferred kind. When | | (RTF and TEXT). And suppose that SurfWriter Text is the preferred kind. When |
− | OpenDoc tries to display the part, its binding subsystem looks first for | + | [[OpenDoc]] tries to display the part, its binding subsystem looks first for |
| SurfWriter -- the last editor that was used. If that isn't found, the binding | | SurfWriter -- the last editor that was used. If that isn't found, the binding |
| subsystem looks for an editor that can read SurfWriter Text -- the preferred | | subsystem looks for an editor that can read SurfWriter Text -- the preferred |
Line 150: |
Line 150: |
| platforms.<p> | | platforms.<p> |
| Now let's look at editor substitution in a little more detail. When attempting | | Now let's look at editor substitution in a little more detail. When attempting |
− | to find an editor to bind to a part, OpenDoc looks first for the editor that | + | to find an editor to bind to a part, [[OpenDoc]] looks first for the editor that |
| last edited the part, specified in the kODPropPreferredEditor property in the | | last edited the part, specified in the kODPropPreferredEditor property in the |
| part's storage unit. If this editor isn't present on the user's system, the | | part's storage unit. If this editor isn't present on the user's system, the |
Line 173: |
Line 173: |
| <br> | | <br> |
| If no editor for any of the part kinds is installed on the user's machine, the | | If no editor for any of the part kinds is installed on the user's machine, the |
− | part remains unviewable and uneditable. But OpenDoc still binds an editor to | + | part remains unviewable and uneditable. But [[OpenDoc]] still binds an editor to |
| the part -- the "editor of last resort." This editor is always available and | | the part -- the "editor of last resort." This editor is always available and |
| represents the part as an icon within the document, so that there's never a | | represents the part as an icon within the document, so that there's never a |
Line 216: |
Line 216: |
| might include the part kinds SurfWriter Text 3.0, SurfWriter Text 2.0, and | | might include the part kinds SurfWriter Text 3.0, SurfWriter Text 2.0, and |
| others.<p> | | others.<p> |
− | OpenDoc looks at a part's category to decide which part editors or part viewers | + | [[OpenDoc]] looks at a part's category to decide which part editors or part viewers |
| can be substituted if an editor is missing and whether to merge or embed data | | can be substituted if an editor is missing and whether to merge or embed data |
| when content is copied from one part into another. Categories are specified by | | when content is copied from one part into another. Categories are specified by |
Line 366: |
Line 366: |
| any of the predefined categories, you can request a new category. The list of | | any of the predefined categories, you can request a new category. The list of |
| predefined categories is maintained by CI Labs, a consortium that coordinates | | predefined categories is maintained by CI Labs, a consortium that coordinates |
− | cross-platform OpenDoc development. See the CI Labs Web page for instructions on how to request a new | + | cross-platform [[OpenDoc]] development. See the CI Labs Web page for instructions on how to request a new |
| category. | | category. |
| <h4> | | <h4> |
Line 385: |
Line 385: |
| <p><li> KindUserString -- lists the part kind user strings</ul>If you request a | | <p><li> KindUserString -- lists the part kind user strings</ul>If you request a |
| new category and CI Labs approves your request, you'll also need a<u> | | new category and CI Labs approves your request, you'll also need a<u> |
− | </u>CategoryUserString resource listing your category user strings. OpenDoc | + | </u>CategoryUserString resource listing your category user strings. [[OpenDoc]] |
| already contains user strings for predefined categories.<p> | | already contains user strings for predefined categories.<p> |
| Listing 1 shows an EditorPlatformKind resource indicating that your editor | | Listing 1 shows an EditorPlatformKind resource indicating that your editor |
Line 486: |
Line 486: |
| to be lost. Only the user should be able to change the preferred kind of a | | to be lost. Only the user should be able to change the preferred kind of a |
| part, and then only through an explicit action. This supports the concept that | | part, and then only through an explicit action. This supports the concept that |
− | content copied into or out of an OpenDoc document should retain its fidelity. | + | content copied into or out of an [[OpenDoc]] document should retain its fidelity. |
| For example, when the user drags a drawing document from the desktop into an | | For example, when the user drags a drawing document from the desktop into an |
− | OpenDoc document and then back to the desktop, the initial document and the | + | [[OpenDoc]] document and then back to the desktop, the initial document and the |
| final document should be identical, as far as the user is concerned. The final | | final document should be identical, as far as the user is concerned. The final |
| document should have the same part kind as the original document, unless the | | document should have the same part kind as the original document, unless the |
| user elects to change the part kind. (See the recipe for promising a | | user elects to change the part kind. (See the recipe for promising a |
− | non-OpenDoc file on the OpenDoc Class Reference CD for more details.)<p> | + | non-[[OpenDoc]] file on the OpenDoc Class Reference CD for more details.)<p> |
| Users can change the preferred kind of a part with the Part Info (or Document | | Users can change the preferred kind of a part with the Part Info (or Document |
| Info) command in the Edit menu. This command brings up a dialog like the one | | Info) command in the Edit menu. This command brings up a dialog like the one |
Line 515: |
Line 515: |
| format. Users are left wondering why their documents can't stick with the | | format. Users are left wondering why their documents can't stick with the |
| format they were created with. <p> | | format they were created with. <p> |
− | To maximize interchange between OpenDoc, traditional applications, and system | + | To maximize interchange between [[OpenDoc]], traditional applications, and system |
− | software, OpenDoc does not arbitrarily promote platform kinds (which, remember, | + | software, [[OpenDoc]] does not arbitrarily promote platform kinds (which, remember, |
− | is our platform-neutral term for Mac OS file types) to OpenDoc part kinds.*<p> | + | is our platform-neutral term for Mac OS file types) to [[OpenDoc]] part kinds.*<p> |
| In today's applications, this unexpected format change is also often associated | | In today's applications, this unexpected format change is also often associated |
| with the creation of a new document named "Untitled x" or "FooDocument - | | with the creation of a new document named "Untitled x" or "FooDocument - |
− | converted." In OpenDoc, parts don't have control over the name of the document, | + | converted." In [[OpenDoc]], parts don't have control over the name of the document, |
| so this errant behavior is prevented. The name of the document, just like the | | so this errant behavior is prevented. The name of the document, just like the |
| preferred kind of a part, should be considered a user setting. Editors | | preferred kind of a part, should be considered a user setting. Editors |
Line 599: |
Line 599: |
| Whenever a user opens a document containing one of your parts, your part must | | Whenever a user opens a document containing one of your parts, your part must |
| be reconstituted from external storage by your InitPartFromStorage method, | | be reconstituted from external storage by your InitPartFromStorage method, |
− | described in detail in the article "Getting Started With OpenDoc Storage" in | + | described in detail in the article "[[Getting Started With OpenDoc Storage]]" in |
| develop Issue 24. Your editor needs to find out the preferred kind and read in | | develop Issue 24. Your editor needs to find out the preferred kind and read in |
| the content data accordingly. <p> | | the content data accordingly. <p> |
Line 607: |
Line 607: |
| to an empty storage unit that's pointing to a file that you should use to | | to an empty storage unit that's pointing to a file that you should use to |
| internalize from. This binding can happen in one of two ways: the user may have | | internalize from. This binding can happen in one of two ways: the user may have |
− | dragged and dropped a traditional Macintosh file onto an OpenDoc document and | + | dragged and dropped a traditional Macintosh file onto an [[OpenDoc]] document and |
| your part editor was bound to the drop, or the user may have opened a | | your part editor was bound to the drop, or the user may have opened a |
− | traditional Macintosh file with the OpenDoc launcher application. For detailed | + | traditional Macintosh file with the [[OpenDoc]] launcher application. For detailed |
| information on how to make this work, see the Drag and Drop Recipes on the | | information on how to make this work, see the Drag and Drop Recipes on the |
| OpenDoc Class Reference CD, specifically the section "Incorporating Data From a | | OpenDoc Class Reference CD, specifically the section "Incorporating Data From a |
Line 648: |
Line 648: |
| accomplish this step.</ul>Note that it's possible for your editor to be bound | | accomplish this step.</ul>Note that it's possible for your editor to be bound |
| to a part that previously had a different editor, as described earlier in | | to a part that previously had a different editor, as described earlier in |
− | "Editor Substitution Explained." In this case, the OpenDoc binding subsystem | + | "Editor Substitution Explained." In this case, the [[OpenDoc]] binding subsystem |
| will automatically notify the user. If your editor doesn't support the | | will automatically notify the user. If your editor doesn't support the |
| preferred kind, use the highest-fidelity kind in the content property that your | | preferred kind, use the highest-fidelity kind in the content property that your |
Line 659: |
Line 659: |
| Whenever a user saves the document, your part must be written out to the | | Whenever a user saves the document, your part must be written out to the |
| storage unit, or externalized, by your Externalize method, described in detail | | storage unit, or externalized, by your Externalize method, described in detail |
− | in the article "Getting Started With OpenDoc Storage" in develop Issue 24. Your | + | in the article "[[Getting Started With OpenDoc Storage]]" in develop Issue 24. Your |
| editor should write out the preferred kind, at a minimum; you may also decide | | editor should write out the preferred kind, at a minimum; you may also decide |
| to write out one or more alternate part kinds, as discussed earlier under | | to write out one or more alternate part kinds, as discussed earlier under |
Line 674: |
Line 674: |
| <p><li> Add values if necessary. Use AddValue to create or recreate the value | | <p><li> Add values if necessary. Use AddValue to create or recreate the value |
| types that you want to externalize in proper fidelity order (from highest | | types that you want to externalize in proper fidelity order (from highest |
− | fidelity to lowest fidelity). Fidelity ordering is important because OpenDoc | + | fidelity to lowest fidelity). Fidelity ordering is important because [[OpenDoc]] |
| looks at it to determine which editor would best edit any given part. | | looks at it to determine which editor would best edit any given part. |
| <p><li> Externalize your content in the format of the preferred kind that your | | <p><li> Externalize your content in the format of the preferred kind that your |
Line 844: |
Line 844: |
| </h4> | | </h4> |
| <ul> | | <ul> |
− | <li> OpenDoc Programmer's Guide for the Mac OS by Apple Computer, Inc. | + | <li> OpenDoc Programmer's Guide for the Mac OS by [[Apple Computer]], Inc. |
| (Addison-Wesley, 1995). This book is accompanied by the OpenDoc Class Reference | | (Addison-Wesley, 1995). This book is accompanied by the OpenDoc Class Reference |
| CD and includes the OpenDoc human interface guidelines. | | CD and includes the OpenDoc human interface guidelines. |
− | <p><li> OpenDoc Cookbook for the Mac OS by Apple Computer, Inc. | + | <p><li> OpenDoc Cookbook for the Mac OS by [[Apple Computer]], Inc. |
| (Addison-Wesley, 1995). | | (Addison-Wesley, 1995). |
− | <p><li> "The OpenDoc User Experience" by Dave Curbow and Elizabeth | + | <p><li> "[[The OpenDoc User Experience]]" by Dave Curbow and Elizabeth |
| Dykstra-Erickson, develop Issue 22. | | Dykstra-Erickson, develop Issue 22. |
− | <p><li> "Getting Started With OpenDoc Storage" by Vincent Lo, develop Issue 24. | + | <p><li> "[[Getting Started With OpenDoc Storage]]" by Vincent Lo, develop Issue 24. |
| <p><li> Byte Guide to OpenDoc by Andrew MacBride and Joshua Susser (Osborne | | <p><li> Byte Guide to OpenDoc by Andrew MacBride and Joshua Susser (Osborne |
| McGraw-Hill, 1996) | | McGraw-Hill, 1996) |
| </ul> | | </ul> |
| | | |
− | [[Category:Apple]] | + | =See Also= |
| + | * [[OpenDoc]] |
| + | * [[Apple Computer]] |
| + | * [[Apple Developer World]] |
| + | |
| + | [[Category:Apple]][[Category:Programming]] |
| + | [[Category:OpenDoc]] |