Difference between revisions of "Development:Third-Party Preference Panes"

From Camino Wiki
Jump to navigation Jump to search
(more revisions)
Line 9: Line 9:
 
These instructions assume a basic working knowledge of Apple's Developer Tools, including Xcode and Interface Builder, as well as the Objective-C language itself. If you are unfamiliar with these, [http://developer.apple.com/ Apple Developer Connection] is an excellent place to start learning.
 
These instructions assume a basic working knowledge of Apple's Developer Tools, including Xcode and Interface Builder, as well as the Objective-C language itself. If you are unfamiliar with these, [http://developer.apple.com/ Apple Developer Connection] is an excellent place to start learning.
  
These instructions should work for anyone developing preference panes on Mac OS X 10.4 or higher, with Xcode 2.4.x or higher and Interface Builder 2.x or higher, to be deployed on any version of Camino from 1.0.x onward.
+
===Applicability and support===
 +
These instructions can be used by anyone developing preference panes on Mac OS X 10.4 or higher, with Xcode 2.4.x or higher and Interface Builder 2.x or higher, to be deployed on any version of Camino from 1.5 onward (thus requiring Mac OS X 10.3.9 or higher). Developers may choose to support only Mac OS X 10.4+ or Camino 2.0pre+, but this is ''highly'' discouraged unless certain limitations of the Mac OS or Camino/Gecko code make supporting Mac OS X 10.3.9 or the Camino 1.5 branch impossible.
 +
 
 +
===Disclaimer===
 +
These instructions are presented in good faith, but we make no guarantees as to the stability of Camino's APIs (even across minor versions), and we cannot guarantee preference panes developed using this guide will not set your cat on fire.
  
 
==Creating the Xcode project==
 
==Creating the Xcode project==
Line 24: Line 28:
 
==Using Camino methods==
 
==Using Camino methods==
  
If you plan to use any of Camino's methods, you'll need to tell the linker how to find a Camino application in order for the -bundle_loader switch to do its job. Again using the Target Info window, point the linker's "Bundle Loader" to a Camino app on your hard disk. For example, if Camino is in your Applications folder, inside a folder called "Internet", it would look like this:
+
If you plan to use any of Camino's methods, your preference pane should be a subclass of the Camino PreferencePaneBase class. This means that PreferencePaneBase.h is a required header. If you plan to deploy your preference pane on Camino 1.5.x, you'll also need to compile PreferencePaneBase.mm (in the Compile Sources phase of the target).
 +
 
 +
In order for the -bundle_loader switch to do its job, you'll need to tell the linker where it can find a Camino application. Using the Target Info window, point the linker's "Bundle Loader" to a copy of Camino on your hard disk. For example, if Camino is in your Applications folder, it would look like this:
  
 
[[Image:Setting-path.png]]
 
[[Image:Setting-path.png]]
Line 36: Line 42:
 
That's it! You should be able to build the project and test your preference pane with Camino. Remember to re-launch Camino after placing the preference pane in [~]/Library/Application Suppport/Camino/PreferencePanes/ .
 
That's it! You should be able to build the project and test your preference pane with Camino. Remember to re-launch Camino after placing the preference pane in [~]/Library/Application Suppport/Camino/PreferencePanes/ .
  
==Other potential gotchas and caveats==
+
==Using Gecko functions and methods==
* It is not currently possible to use Gecko code directly in third-party preference panes. If there's something you really need to use that simply doesn't have a Cocoa wrapper on it in Camino, please bring it to our attention. We may be willing to add wrapper code for it, since one architectural goal we have for Camino is to hide Gecko from our Cocoa developers as much as possible.
 
 
 
==Error messages==
 
  
===Undefined Symbols===
+
Using Gecko code in a third-party preference pane is somewhat more involved. You'll need to copy the proper headers (see above) and link against the appropriate libraries. ''[An example here would be great. -cl]''
  
''it compiles ok, but if it's in deployment mode I get an undefined symbol error'' [Is this still a problem with -bundle_loader? -cl]
+
If there's something in Gecko you really need to use that simply doesn't have a Cocoa wrapper on it in Camino, please bring it to our attention. We may be willing to add wrapper code for it, since one architectural goal we have for Camino is to hide Gecko from our developers as much as possible.
  
* Get info on your target (or project) and set "Other Linker Flags" to "-undefined dynamic_lookup" for all configurations
+
==Other potential gotchas and caveats==
* You only need the appropriate header files (the header files for the classes you're using/subclassing) if you're using -undefined dynamic_lookup; you don't need to link against the Gecko code (often, this is just PrefPaneBase.h)
 
 
 
===Camino doesn't like my prefPane; it says it has to have a 'MOZC' signature===
 
  
* Get Info on your prefpane target
+
Crossing that bridge when we come to it...
* Go to "Properties"
 
* Change the "Creator" field to "MOZC" (without quotes)
 

Revision as of 15:17, 21 December 2007

DRAFT
This page is not complete.

See Bug 384800 for more information on the status of this page. The current how-to should not be attempted by people unfamiliar with Xcode and its related tools or the Camino codebase.

Who should read this document?

Camino, per our mission statement, "is an open source web browser developed with a focus on providing the best possible experience for Mac OS X users." This, along with the limited time available for our all-volunteer programming team to implement features, means that certain choices have to be made about what should and shouldn't be part of the Camino application itself. As with Firefox extensions, there are many opportunities for third-party developers to step in and provide niche features or UI for things that Camino doesn't provide by default. This document is intended to provide a jumping-off point for third-party developers interested in developing additional preference panes for Camino.

Getting started

These instructions assume a basic working knowledge of Apple's Developer Tools, including Xcode and Interface Builder, as well as the Objective-C language itself. If you are unfamiliar with these, Apple Developer Connection is an excellent place to start learning.

Applicability and support

These instructions can be used by anyone developing preference panes on Mac OS X 10.4 or higher, with Xcode 2.4.x or higher and Interface Builder 2.x or higher, to be deployed on any version of Camino from 1.5 onward (thus requiring Mac OS X 10.3.9 or higher). Developers may choose to support only Mac OS X 10.4+ or Camino 2.0pre+, but this is highly discouraged unless certain limitations of the Mac OS or Camino/Gecko code make supporting Mac OS X 10.3.9 or the Camino 1.5 branch impossible.

Disclaimer

These instructions are presented in good faith, but we make no guarantees as to the stability of Camino's APIs (even across minor versions), and we cannot guarantee preference panes developed using this guide will not set your cat on fire.

Creating the Xcode project

Camino's preference panes are standard Apple PreferencePanes with a small twist: their creator code is MOZC (Camino's creator code) instead of the default "????". You can change this in the Properties tab of Xcode's Target Info window (see screenshot).

Error creating thumbnail: Unable to save thumbnail to destination

We've put together a [CBSamplePane.zip sample Xcode project] (download size) for developers to use when writing preference panes for Camino. Feel free to use this project as a starting point, or make your own.

Laying out the UI

In order to keep the UI of your preference panes as consistent as possible with the preference panes shipped with Camino itself, please use our NIB Editing Guide as a reference for laying out the UI when developing preference panes for Camino.

Using Camino methods

If you plan to use any of Camino's methods, your preference pane should be a subclass of the Camino PreferencePaneBase class. This means that PreferencePaneBase.h is a required header. If you plan to deploy your preference pane on Camino 1.5.x, you'll also need to compile PreferencePaneBase.mm (in the Compile Sources phase of the target).

In order for the -bundle_loader switch to do its job, you'll need to tell the linker where it can find a Camino application. Using the Target Info window, point the linker's "Bundle Loader" to a copy of Camino on your hard disk. For example, if Camino is in your Applications folder, it would look like this:

Error creating thumbnail: Unable to save thumbnail to destination

If you have multiple copies of Camino, point it to the oldest one you plan to support with your preference pane.

You'll also need to copy over any Camino header files for methods you're using in your preference pane. You can add them to the Copy Headers phase of the project, like this:

Error creating thumbnail: Unable to save thumbnail to destination

That's it! You should be able to build the project and test your preference pane with Camino. Remember to re-launch Camino after placing the preference pane in [~]/Library/Application Suppport/Camino/PreferencePanes/ .

Using Gecko functions and methods

Using Gecko code in a third-party preference pane is somewhat more involved. You'll need to copy the proper headers (see above) and link against the appropriate libraries. [An example here would be great. -cl]

If there's something in Gecko you really need to use that simply doesn't have a Cocoa wrapper on it in Camino, please bring it to our attention. We may be willing to add wrapper code for it, since one architectural goal we have for Camino is to hide Gecko from our developers as much as possible.

Other potential gotchas and caveats

Crossing that bridge when we come to it...