Eloy Duran
eloy.****@gmail*****
Sat Apr 12 02:33:49 JST 2008
Hi Scott, First of all, thanks a lot for the tremendous amount of work you've put into documenting it. I have added the long version to the wiki: And I've updated the rdoc version a bit; replaced "routine" with "method" and some punctuation. If nobody else has any objections then I'll add this tomorrow. # The OSX::require_framework method imports Mac OS X frameworks and uses the # BridgeSupport metadata to add Ruby entry points for the framework's Classes, # methods, and Constants into the OSX module. # # The framework parameter is a reference to the framework that should be # imported. This may be a full path name to a particular framework, a shortcut, # or a framework name. The shortcuts are the keys listed in the # <tt>QUICK_FRAMEWORKS</tt> hash. # # If a framework name (with no path) is given, then the method searches a number # of directories. Those directories (in search order) are: # 1. /System/Library/Frameworks # 2. /Library/Frameworks # 3. Any directories in the RUBYCOCOA_FRAMEWORK_PATHS array, if defined # 4. ENV['HOME']/Library/Frameworks, if the HOME environment variable is defined # # When using the search paths, the <tt>.framework</tt> file type extension should # be omitted from the framework name passed to the method. # # If the method loads the framework successfully, it returns <tt>true</ tt>. # If the framework was already loaded the method returns <tt>false</tt>. # If the method is unable to locate, or unable to load the framework then it # raises an <tt>ArgumentError</tt>. def require_framework(framework) end Cheers, Eloy On 11 apr 2008, at 15:53, Scott Thompson wrote: > Howdy, List. > > Jonkheer Eloy Druan and I were discussing documentation for > require_framework on the rubycocoa-talk list. The brunt of the > conversation was my asking if there was any documentation and his > telling me that there wasn't any, but, if I wanted to, I could look > at the code and write some. > > So I did :-P > > THEN he asked me to post it to this list. So here I go. > > Please find attached two files. The first is > require_framework_doc.rtf. This document is an RTF (TextEdit) > document that is intended to find it's way to the http://rubycocoa.sourceforge.net/Documentation > page. The second, require_framework.rdoc.rb is a stub ruby file > with an RDoc-style comment that is intended to be copied and pasted > into the source above the definition of require_framework. > > My next task is to take the rtf file and rework it to use wikka > style markup so it can be more easily posted on the web site. > However, I would like to ask the folks here to review the > documentation and let me know if it is inaccurate, incomplete, or if > there are unclear sections. Constructive criticism is most welcome. > > If you don't want to reply to the list, you may send your feedback > directly to me at easco at mac dot com. > > Thanks! > > Scott Thompson > > <require_framework.rdoc.rb>{\rtf1\ansi > \ansicpg1252\cocoartf949\cocoasubrtf270 > {\fonttbl\f0\fnil\fcharset0 Verdana;\f1\fmodern\fcharset0 Courier; > \f2\fmodern\fcharset0 Courier-Bold; > } > {\colortbl;\red255\green255\blue255;\red0\green0\blue0;} > \margl1440\margr1440\vieww20680\viewh14180\viewkind0 > \pard > \tx720 > \tx1440 > \tx2160 > \tx2880 > \tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural > > \f0\fs26 \cf0 This article discusses the functionality of the > RubyCocoa > \f1 require_framework > \f0 method. This method allows an application to load a Mac OS X > framework and makes that framework's entry points and constants > available through the OSX module. \ > \ > For more information on Frameworks on Mac OS X, please see the \ul > Framework Programming Guide\ulnone [http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Frameworks.html > ] > \ > \pard\pardeftab720\sl400 > \cf0 \ > > \b Loading Frameworks with > \f2 OSX.require_framework > \f0\b0 > \ > \ > The > \f1 require_framework > \f0 method in the > \f1 OSX > \f0 module gives RubyCocoa applications a mechanism for loading > frameworks into memory and including Ruby entry points for their > symbols in that module. From the perspective of the Ruby > application, the effect is very similar to that of using a Ruby's > include statement to include the instance methods one module into > another.\ > \ > Like the Ruby method > \f1 Kernel#require > \f0 , the > \f1 require_framework > \f0 method takes a single argument. That argument is a string that > defines which framework the routine should import. Fundamentally, > the string represents the file system path to the framework you want > to load. In typical Ruby fashion, however, there is some flexibility > built into the > \f1 require_framework > \f0 that makes it easy to bring in common frameworks. Both the > fundamental and more convenient mechanisms are worth a further look.\ > \ > > \b The Fundamental Case\ > \ > > \b0 The simplest parameter to > \f1 require_framework > \f0 is an absolute file system path to the framework it should > load. A common example is presented in Apple's developer > documentation in the context of a RubyCocoa application that wants > to take advantage of the Scripting Bridge in Mac OS X 10.5 Leopard. > In this case, a Ruby application can provide a full path to the > operating system's > \f1 ScriptingBridge.framework > \f0 . > \f1 Here is an example: > \f0 \ > \ > > \f1 OSX.require_framework '/System/Library/Frameworks/ > ScriptingBridge.framework'\ > \ > > \f0 After executing this line, if the load is successful, the > \f1 OSX > \f0 module will include the classes, functions, and constants of > the Scripting Bridge Framework. For example, the > \f1 OSX > \f0 module would include the > \f1 SBApplication > \f0 class which bridges to the Objective-C class of the same name. > The application could continue by creating an instance of > \f1 SBApplication > \f0 to communicate with the application of their choice:\ > \ > > \f1 safari_app = > OSX > ::SBApplication.applicationWithBundleIdentifier("com.apple.Safari")\ > safari_app.documents[0].URL = 'http://rubycocoa.sourceforge.net/HomePage' > \ > \ > > \f0 This same technique could be used to load a custom framework > from anywhere within the file system. The RubyCocoa application > could use any of a variety of techniques to locate a framework and > then load that framework by using its full path.\ > \ > > \b Built-in Conveniences\ > \ > > \b0 Having to supply a full pathname to a framework every time can > be inconvenient. Particularly when working with nested frameworks > like Apple's umbrella frameworks. Fortunately > \f1 require_framework > \f0 also supports some convenient shortcuts for common frameworks. > In taking advantage of those shortcuts, an application supplies the > name of a framework, and the > \f1 require_framework > \f0 method will try to construct a full path to that framework > through a set of built-in framework search paths. The method will > also recognize some special shortcuts to common frameworks found in > the system's umbrella frameworks.\ > \ > \ul Search Paths\ulnone \ > \ > You can pass require_framework the name of a framework without its > base directory. In this case, RubyCocoa will search a set of > directories looking for a framework with that name and try to load > the first instance of the framework that it finds.\ > \ > Two important paths that RubyCocoa will search are the Frameworks > folders in the user and system file system domains (For more > information on File System Domains and the Library Directory, please > see the \ul File System Overview\ulnone [http://developer.apple.com/documentation/MacOSX/Conceptual/BPFileSystem/BPFileSystem.html > ]). Those two directories are:\ > \ > > \f1 /System/Library/Frameworks\ > /Library/Frameworks > \f0 \ > \ > A RubyCocoa application can add to these basic search paths by > defining the constant > \f1 RUBYCOCOA_FRAMEWORK_PATHS. > \f0 If provided, this constant should be an array of additional > directories that should be searched when looking for a framework. > For example:\ > \ > RUBYCOCOA_FRAMEWORK_PATHS = ["/Users/scott/MyCustomSoftware/ > Frameworks"]\ > OSX.require_framework 'HandyCustomFramework.framework'\ > \ > Can be used to include a framework at the path:\ > \ > /Users/scott/MyCustomSoftware/Frameworks/ > HandyCustomFramework.framework\ > \ > In addition, if you are running RubyCocoa in an environment where > the environment variable > \f1 HOME > \f0 is defined, Ruby will also look in a framework and library > folder based at that directory. For example, if the value of > \f1 HOME > \f0 is > \f1 /Users/scott > \f0 then Ruby will also search the directory:\ > \ > > \f1 /Users/scott/Library/Frameworks > \f0 \ > \ > If the framework to be loaded is in those directories then it is > sufficient to simply supply the framework name to > \f1 require_framework > \f0 . To return to the first example, Scripting Bridge framework can > be included simply with the line:\ > \ > > \f1 OSX.require_framework 'ScriptingBridge.framework'\ > \ > > \f0 In fact, if you leave off the " > \f1 .framework > \f0 " extension, the routine will add it for you. In short, the > statement:\ > \ > > \f1 OSX.require_framework 'ScriptingBridge'\ > \ > > \f0 will work just as well. It is this last form that is most often > seen in code samples.\ > \ > \ul Umbrella Frameworks and Predefined Shortcuts\ulnone \ > \ > Mac OS X has the concept of an "Umbrella Framework". An umbrella > framework is a Mac OS X framework that contains other frameworks > (these contained frameworks are also called subframeworks). In > traditional Mac OS X development, an application could link to the > umbrella framework in order to import all the functionality of its > subframeworks. In fact, it is possible for one umbrella framework > to contain subframeworks that are, themselves, umbrella frameworks. > One example of an umbrella framework in Leopard is the > ApplicationServices framework which contains, among others, the > ImageIO, ColorSync, and CoreGraphics frameworks. (for more > information on Umbrella Frameworks see the \ul Framework Programming > Guide\ulnone [http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html > ])\ > \ > When > \f1 require_framework > \f0 is asked to import an umbrella framework, it does NOT import > the subframeworks. Instead, the subframeworks of an umbrella > framework must be loaded explicitly. That means that loading the > \f1 ImageIO > \f0 framework is done by a > \f1 require_framework > \f0 statement like:\ > \ > > \f1 OSX.require_framework '/System/Library/Frameworks/ > ApplicationServices.framework/Versions/Current/Frameworks/ > ImageIO.framework'\ > > \f0 \ > Long path names like this can be tedious and > \f1 require_framework > \f0 includes some convenient shortcuts for popular frameworks. To > use a shortcut, you simply pass its name to > \f1 require_framework > \f0 . The method will convert the shortcut passed in into the > common location for that framework as indicated by the following > table:\ > \ > \ul Shortcut name\ulnone \ul Framework path\ulnone \ > \pard\pardeftab720 > > \f1 \cf2 CoreGraphics /System/Library/Frameworks/ > ApplicationServices.framework/Frameworks/CoreGraphics.framework\ > PDFKit /System/Library/Frameworks/Quartz.framework/Frameworks/ > PDFKit.framework\ > QuartzComposer /System/Library/Frameworks/Quartz.framework/ > Frameworks/QuartzComposer.framework\ > ImageKit /System/Library/Frameworks/Quartz.framework/Frameworks/ > ImageKit.framework > \f0 \ > \cf0 \ > \pard\pardeftab720\sl400\ql\qnatural > \cf0 \ul \ulc0 Search Order\ > \ > \pard\pardeftab720\sl400\ql\qnatural > \cf0 \ulnone When using the convenience routines to load frameworks, > the order in which the > \f1 require_framework > \f0 traverses the search paths and the shortcuts can be significant. > \f1 require_framework > \f0 searches for frameworks using the following rules:\ > \ > 1. If the routine is passed a full path to a framework (and the > method assumes that any string passed to it which begins with the > directory separator character '/' is a full path to a framework) then > \f1 require_framework > \f0 will try to load that framework explicitly.\ > 2. If one of the shortcuts for the subframeworks listed above is > given, then the computer will load the corresponding system > framework.\ > 3. If none of these other criteria is met, the routine searches the > framework directory paths in this order:\ > \ > a. > \f1 /System/Library/Frameworks > \f0 \ > b. > \f1 /Library/Frameworks > \f0 \ > c.\'a0The paths specified by the > \f1 RUBYCOCOA_FRAMEWORK_PATHS > \f0 constant, if it is defined\ > d.\'a0The path specified by the > \f1 HOME > \f0 environment variable, if it is defined\ > \ > > \i Note: The File System Overview documentation, in the section on > Searching Within the File-System Domains > \i0 [http://developer.apple.com/documentation/MacOSX/Conceptual/BPFileSystem/Articles/Domains.html > ] > \i recommends searching the domain paths by starting with the user > domain, then the local domain, and finally the user domain. > \f1\i0 require_framework > \f0\i searches these paths in the exact opposite order and inserts > the RUBYCOCOA_FRAMEWORK_PATHS in-between the local and user domains. > \i0 \ > \ > \pard\pardeftab720\sl400\ql\qnatural > > \b \cf0 Return Value and Exceptions\ > \ > \pard\pardeftab720\sl400\ql\qnatural > > \b0 \cf0 If > \f1 require_framework > \f0 successfully loads a framework, it returns > \f1 true > \f0 . If asked to _______________________________________________ > Rubycocoa-devel mailing list > Rubyc****@lists***** > http://lists.sourceforge.jp/mailman/listinfo/rubycocoa-devel
