Plugins for VCL
事業／計画（する） Owner: Philipp Lohmann, last change: 2004/01/28
現在／一般に only 利用できる for Unix 壇・綱領・公約s: plugins move the whole 壇・綱領・公約 扶養家族 part of VCL(Unix) into an own library. At runtime OOo decides what plugin would 控訴 the 現在の desktop 環境 best; e.g. it uses a gtk based plugin on GNOME desktops or a generic (plain Xlib based) plugin on CDE. The 創立／基礎 for this the pure abstraction of all Sal interfaces (Sal: System Abstraction 層 – the 指名する is sadly coincidental with the sal 事業／計画（する）; the Sal 層 in vcl 存在するd first 歴史的に).
Why plugins ?
For better system 統合，差別撤廃 it is necessary to run the system's toolkit inside the OOo 過程 space. E.g. to use toolkit 主題s for 製図／抽選 支配（する）／統制するs it is imperative to be able to ask the native toolkit to draw OOo's 支配（する）／統制するs. Also toolkits know how to 接近 system features like 最近の 文書 名簿（に載せる）／表（にあげる）s, とじ込み／提出する 対話s, etc..
What are the basics for 令状ing a VCL(Unix) plugin ?
The starting point for a new VCL plugin is SalInstance. This is a factory interface the 実施 of which produces instances of all other Sal interfaces. At startup the 独立した・無所属 part of vcl tries to 決定する the 訂正する plugin (desktop autodetection) and then tries to 負担 that library and ask it for a SalInstance 反対する. Every other Sal interface implentation is produced 経由で the corresponding method of SalInstance (see vcl/inc/salinst.hxx for 詳細（に述べる）s).
SalInstance
The first step is to create an extern
"C" 機能（する）／行事 指名するd create_SalInstance which
returns the SalInstance of your plugin. For many plugins it is
advantageous to 相続する their SalInstance from the SalInstance of the
generic 実施 so the new plugin can 再使用する the generic
実施 where appropriate; good examples for 実施s
that can be 相続するd are SalSound, SalBitmap, SalGraphics and
SalPrinter. 特に SalGraphics should be used from the generic
実施 as it 含む／封じ込めるs really difficult stuff like 製図／抽選
text with コンビナート／複合体 text layout (CTL) that would be a real 苦痛 to
器具／実施する with little 伸び（る） since the result should still look like
the result of the generic SalGraphics. Still, if you want to
器具／実施する every Sal interface on your own there is of course nothing
to stop you from doing that.
SalInstance is also 責任がある the 使用／適用 main 宙返り飛行 and the SolarMutex (the mutex vcl gets its thread 認識／意識性 from). Since toolkits tend to be nonfunctional without their own main 宙返り飛行, this is the first feature you should 器具／実施する. The methods GetYieldMutex, ReleaseYieldMutex and AcquireYieldMutex must return a vos::IMutex interface (see vos/inc/vos/mutex.hxx) that synchronizes to the mutex of your special toolkit. Then 産する／生じる must be 器具／実施するd. 産する／生じる is VCL's interface to the system main 宙返り飛行; when called it should look for all 肉親，親類d of events (e.g. X events) and 派遣（する） them 適切な. If called with parameter bWait 始める，決める to TRUE it should wait until an event is 利用できる and then 派遣（する） it. If bWait is FALSE 産する／生じる should 派遣（する） all events already 利用できる and then return すぐに.
Please 公式文書，認める that this may be far from trivial to 器具／実施する depending on your toolkit since so much depends on the main 宙返り飛行. Unless you 器具／実施する every Sal interface yourself it is 基本的に necessary to 相続する from the SalDisplay, SalXLib and SalData classes of the generic 実施 since these lay the 基礎 for most other generic 実施s (X11SalFrame, X11SalTimer, etc.). E.g. SalData 追加するs とじ込み／提出する descriptors to be watched for events in the main 宙返り飛行. To make this feasible the corresponding methods on the SalXLib, SalData and SalDisplay are 事実上の so a new 実施 can overload these and still use the generic 実施.
SalFrame
The next step is most likely 器具／実施するing the SalFrame interface. This is necessary for the に引き続いて 推論する／理由s:
If you want to use any window inside your toolkit you most likely need a parent that already is a such a toolkit window; e.g. if you want to have native とじ込み／提出する 対話s you'll want to have a 文書 window as their “parent”(or rather make the 対話 window make transient for the 文書 window in X speak).
SalFrame reads the native system settings, so if you want to have OOo's UI using the 訂正する colors and fonts you'll need to 器具／実施する at least the UpdateSettings method.
When 器具／実施するing SalFrame you must 打ち勝つ the に引き続いて problems:
SalFrame produces a SalGraphics; here you most likely want to 相続する from the generic 実施. The X11SalGraphics for a でっちあげる，人を罪に陥れる needs to be initialized with a native X drawable, so you need to get the Xlib Window from your native 最高の，を越す-level widget. You also need the Xlib Window to 器具／実施する the GetSystemData method.
SalFrame needs to 過程 internationalized input; there is most likely an abstraction inside your toolkit you'll want to use, so be 用意が出来ている to send VCL's abstracted input method (IM) events instead of simple 重要な events.
SalFrame can be 建設するd as a child window of a native window (this is used e.g. in the SDK's java bean where you plug OOo into another 使用／適用). You'll need to find an appropriate widget to do that with your toolkit (e.g. like a GtkPlug in gtk).
You must 妨げる you でっちあげる，人を罪に陥れる widget from 製図／抽選 its own background as this would 干渉する with VCL's 支配（する）／統制するs which draw themselves 直接／まっすぐに の上に the window without 存在 known to your toolkit.
SalObjects
If you have 器具／実施するd SalFrame, you'll need to 器具／実施する SalObject, too. SalObject is a child window of a SalFrame 保証（人）d to be a native system window (that is in Xtoolkit 条件 a widget rather than a gadget). This is needed for plugins and java applets inside 文書s. There are only two 障害s doing this as SalObject is really rather boring:
You need to find an appropriate widget (a 製図／抽選 area will 一般に do)
Since the SalObject is embedded into a lot of gadgets (which is what VCL's 支配（する）／統制するs are from a toolkit 見地), a real widget will overlap them if any geometry is 株d. This would e.g. lead to a plugin 製図／抽選 over OOo's toolbars if you scroll the corresponding 文書 負かす／撃墜する slowly. To 避ける this SalObject windows need to be 形態／調整d using the X SHAPE 拡張.
General considerations
While 器具／実施するing your own plugin you may find it necessary to change something inside the generic plugin. Please do so if it 控訴s you, but 接触する one of the vcl team (e.g. The author of this 文書) to check whether your change does not break anything for other 実施s.
In general it may be a good idea to 接触する the vcl developers before and during the 実施 on the dev@gsl.openoffice.org mailinglist as all 肉親，親類d of questions may arise (特に considering that VCL is 大部分は undocumented code up today).
