diff --git a/src/documentation/Jamfile b/src/documentation/Jamfile index b3c3009272..5be7ab36ec 100644 --- a/src/documentation/Jamfile +++ b/src/documentation/Jamfile @@ -2,6 +2,5 @@ SubDir HAIKU_TOP src documentation ; SEARCH on license.xml = [ FDirName $(HAIKU_TOP) src documentation ] ; -SubInclude HAIKU_TOP src documentation haiku_book ; SubInclude HAIKU_TOP src documentation uiguidelines ; SubInclude HAIKU_TOP src documentation shell_tools ; diff --git a/src/documentation/haiku_book/Haiku_Book.xml b/src/documentation/haiku_book/Haiku_Book.xml deleted file mode 100644 index 69d84c2347..0000000000 --- a/src/documentation/haiku_book/Haiku_Book.xml +++ /dev/null @@ -1,85 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - -Haiku'> - - -]> - - - - Haiku Book - 2005-05-16 - - - Jerome - Duval - - - Matthijs - Hollemans - - - - - - This guide is the documentation for the C and C++ API of &haiku;. - - - - - - 1.00 - 2005-05-16 - kor - Initial version. - - - - - - - &appkit; - &devicekit; - &gamekit; - &interfacekit; - &kernelkit; - &mailkit; - &mediakit; - &midikit; - &networkkit; - &openglkit; - &storagekit; - &supportkit; - &translationkit; - - - &license; - diff --git a/src/documentation/haiku_book/Jamfile b/src/documentation/haiku_book/Jamfile deleted file mode 100644 index 80ec18ed1a..0000000000 --- a/src/documentation/haiku_book/Jamfile +++ /dev/null @@ -1,106 +0,0 @@ -SubDir HAIKU_TOP src documentation haiku_book ; - -SetSubDirSupportedPlatformsBeOSCompatible ; - -Doc2HTML - Haiku_Book.xml - : index.html - : [ FDirName $(HAIKU_TOP) src documentation docbook-xsl html chunk.xsl ] - : Haiku_Book - : - : -stringparam use.id.as.filename 1 -stringparam language cpp -stringparam chunk.section.depth 2 - ; - -Doc2HTML - howto.xml - : Haiku_Book_Howto.html - : [ FDirName $(HAIKU_TOP) src documentation docbook-xsl html chunk.xsl ] - : Haiku_Book_Howto - : - : -stringparam language cpp - ; - -# Single most ugly string manipulation ever ... -rule FRelGristFiles -{ - #local targets = $(1) ; - - #local fallbackgrist = $(2:J=!) ; - #local gristval = $(SOURCE_GRIST:E=$(fallbackgrist)) ; - - #local sourcegrist = $(targets:G=gristval) ; - #return $(targets:G=$(gristval)) ; - - return $(<:G=$(SOURCE_GRIST:E)$(>:J=!)) ; -} - -local chapter_files = appkit.xml -devicekit.xml -gamekit.xml -interfacekit.xml -kernelkit.xml -mailkit.xml -mediakit.xml -midikit.xml -networkkit.xml -openglkit.xml -storagekit.xml -supportkit.xml -translationkit.xml ; - -Includes [ FGristFiles Haiku_Book.xml ] - : [ FGristFiles $(chapter_files) ] license.xml ; -SEARCH on [ FGristFiles $(chapter_files) ] = [ FDirName $(SUBDIR) ] ; - -local app_files = intro.xml messaging.xml scripting.xml Application.xml ; -Includes [ FGristFiles appkit.xml ] : [ FRelGristFiles $(app_files) : app ] ; -SEARCH on [ FRelGristFiles $(app_files) : app ] = [ FDirName $(SUBDIR) app ] ; - -local device_files = intro.xml Joystick.xml SerialPort.xml ; -Includes [ FGristFiles devicekit.xml ] : [ FRelGristFiles $(device_files) : device ] ; -SEARCH on [ FRelGristFiles $(device_files) : device ] = [ FDirName $(SUBDIR) device ] ; - -local game_files = intro.xml ; -Includes [ FGristFiles gamekit.xml ] : [ FRelGristFiles $(game_files) : game ] ; -SEARCH on [ FRelGristFiles $(game_files) : game ] = [ FDirName $(SUBDIR) game ] ; - -local interface_files = intro.xml ; -Includes [ FGristFiles interfacekit.xml ] : [ FRelGristFiles $(interface_files) : interface ] ; -SEARCH on [ FRelGristFiles $(interface_files) : interface ] = [ FDirName $(SUBDIR) interface ] ; - -local kern_files = intro.xml threads.xml ports.xml sems.xml ; -Includes [ FGristFiles kernelkit.xml ] : [ FRelGristFiles $(kern_files) : kernel ] ; -SEARCH on [ FRelGristFiles $(kern_files) : kernel ] = [ FDirName $(SUBDIR) kernel ] ; - -local mail_files = intro.xml ; -Includes [ FGristFiles mailkit.xml ] : [ FRelGristFiles $(mail_files) : mail ] ; -SEARCH on [ FRelGristFiles $(mail_files) : mail ] = [ FDirName $(SUBDIR) mail ] ; - -local media_files = intro.xml ; -Includes [ FGristFiles mediakit.xml ] : [ FRelGristFiles $(media_files) : media ] ; -SEARCH on [ FRelGristFiles $(media_files) : media ] = [ FDirName $(SUBDIR) media ] ; - -local midi_files = intro.xml midi2.xml midi2consumer.xml midi2endpoint.xml midi2localproducer.xml midi2roster.xml - midi1.xml midi2api.xml midi2defs.xml midi2localconsumer.xml midi2producer.xml ; -Includes [ FGristFiles midikit.xml ] : [ FRelGristFiles $(midi_files) : midi ] ; -SEARCH on [ FRelGristFiles $(midi_files) : midi ] = [ FDirName $(SUBDIR) midi ] ; - -local network_files = intro.xml ; -Includes [ FGristFiles networkkit.xml ] : [ FRelGristFiles $(network_files) : network ] ; -SEARCH on [ FRelGristFiles $(network_files) : network ] = [ FDirName $(SUBDIR) network ] ; - -local opengl_files = intro.xml ; -Includes [ FGristFiles openglkit.xml ] : [ FRelGristFiles $(opengl_files) : opengl ] ; -SEARCH on [ FRelGristFiles $(opengl_files) : opengl ] = [ FDirName $(SUBDIR) opengl ] ; - -local storage_files = intro.xml ; -Includes [ FGristFiles storagekit.xml ] : [ FRelGristFiles $(storage_files) : storage ] ; -SEARCH on [ FRelGristFiles $(storage_files) : storage ] = [ FDirName $(SUBDIR) storage ] ; - -local support_files = intro.xml ; -Includes [ FGristFiles supportkit.xml ] : [ FRelGristFiles $(support_files) : support ] ; -SEARCH on [ FRelGristFiles $(support_files) : support ] = [ FDirName $(SUBDIR) support ] ; - -local translation_files = intro.xml ; -Includes [ FGristFiles translationkit.xml ] : [ FRelGristFiles $(translation_files) : translation ] ; -SEARCH on [ FRelGristFiles $(translation_files) : translation ] = [ FDirName $(SUBDIR) translation ] ; diff --git a/src/documentation/haiku_book/app/Application.xml b/src/documentation/haiku_book/app/Application.xml deleted file mode 100644 index 4825096a4f..0000000000 --- a/src/documentation/haiku_book/app/Application.xml +++ /dev/null @@ -1,148 +0,0 @@ - - - - - BApplication - - Member Functions - - - BApplication() - BApplicationconstchar *signature -BApplicationconstchar *signaturestatus_t *error -BApplicationBMessage *data - - - - - ~BApplication() - virtual~BApplication - - - - Instanciate() - staticBArchivable *InstantiateBMessage *data - - - - Archive() - virtualstatus_tArchiveBMessage *databooldeeptrueconst - - - - InitCheck() -status_tInitCheckconst - - - Run() - virtualthread_idRun - - - Quit() - virtualQuit - - - QuitRequested() - virtualboolQuitRequested - - - Pulse() - virtualPulse - - - ReadyToRun() - virtualReadyToRun - - - MessageReceived() - virtualMessageReceivedBMessage *msg - - - ArgvReceived() - virtualArgvReceivedint32argcchar * *argv - - - AppActivated() - virtualAppActivatedboolactive - - - RefsReceived() - virtualRefsReceivedBMessage *message - - - AboutRequested() - virtualAboutRequested - - - ResolveSpecifier() - virtualBHandler *ResolveSpecifierBMessage *msgint32indexBMessage *specifierint32formconstchar *property - - - ShowCursor() - ShowCursor - - - HideCursor() - HideCursor - - - ObscureCursor() - ObscureCursor - - - IsCursorHidden() - boolIsCursorHiddenconst - - - SetCursor - SetCursorconstvoid *cursor - SetCursorconstBCursor *cursorboolsynctrue - - - CountWindows() - int32CountWindowsconst - - - WindowAt() - BWindow *WindowAtint32indexconst - - - CountLoopers() - int32CountLoopersconst - - - LooperAt() - BLooper *LooperAtint32indexconst - - - IsLaunching - boolIsLaunchingconst - - - GetAppInfo() - status_tGetAppInfoapp_info *infoconst - - - AppResources() - staticBResources *AppResources - - - DispatchMessage() - virtualDispatchMessageBMessage *messageBHandler *handler - - - SetPulseRate() - SetPulseRatebigtime_trate - - - GetSupportedSuites() - virtualstatus_tGetSupportedSuitesBMessage *data - - - Perform() - virtualstatus_tPerformperform_codedvoid *arg - - diff --git a/src/documentation/haiku_book/app/intro.xml b/src/documentation/haiku_book/app/intro.xml deleted file mode 100644 index 683a16d935..0000000000 --- a/src/documentation/haiku_book/app/intro.xml +++ /dev/null @@ -1,25 +0,0 @@ - - - - - Introduction - - - Application Kit is about classes needed to interact with other applications or the screen. Information about it is available in several topics : - - - - - helps to send and receive data from other processes. - - - helps to operate by program on other applications. - - - describes an application object. Each application creates one instance to register with the system. - - - diff --git a/src/documentation/haiku_book/app/messaging.xml b/src/documentation/haiku_book/app/messaging.xml deleted file mode 100644 index 84494deb2d..0000000000 --- a/src/documentation/haiku_book/app/messaging.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - -Messaging - - diff --git a/src/documentation/haiku_book/app/scripting.xml b/src/documentation/haiku_book/app/scripting.xml deleted file mode 100644 index cb3a026d3f..0000000000 --- a/src/documentation/haiku_book/app/scripting.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - -Scripting - - diff --git a/src/documentation/haiku_book/appkit.xml b/src/documentation/haiku_book/appkit.xml deleted file mode 100644 index 8ca835a5c6..0000000000 --- a/src/documentation/haiku_book/appkit.xml +++ /dev/null @@ -1,11 +0,0 @@ - - - - The Application Kit - - - - - - - diff --git a/src/documentation/haiku_book/device/Joystick.xml b/src/documentation/haiku_book/device/Joystick.xml deleted file mode 100644 index 7e566a1f8d..0000000000 --- a/src/documentation/haiku_book/device/Joystick.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - BJoystick - diff --git a/src/documentation/haiku_book/device/SerialPort.xml b/src/documentation/haiku_book/device/SerialPort.xml deleted file mode 100644 index 5f78727ea5..0000000000 --- a/src/documentation/haiku_book/device/SerialPort.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - BSerialPort - diff --git a/src/documentation/haiku_book/device/intro.xml b/src/documentation/haiku_book/device/intro.xml deleted file mode 100644 index 31b03432a7..0000000000 --- a/src/documentation/haiku_book/device/intro.xml +++ /dev/null @@ -1,23 +0,0 @@ - - - - - Introduction - - - The Device Kit provides a collection of classes which provide a programmer a convenient interface with hardware devices attached to the computer. These classes free one from dealing with extraneous details, instead focusing on the device itself. - - - - - facilitates usage of an RS-232 port. - - - allows polling of any joystick or gamepad. - - - - diff --git a/src/documentation/haiku_book/devicekit.xml b/src/documentation/haiku_book/devicekit.xml deleted file mode 100644 index 2a4cc63f85..0000000000 --- a/src/documentation/haiku_book/devicekit.xml +++ /dev/null @@ -1,11 +0,0 @@ - - - - The Device Kit - - - - - - - diff --git a/src/documentation/haiku_book/game/intro.xml b/src/documentation/haiku_book/game/intro.xml deleted file mode 100644 index ded076f84e..0000000000 --- a/src/documentation/haiku_book/game/intro.xml +++ /dev/null @@ -1,17 +0,0 @@ - - - - - Introduction - - - The Game Kit consists of a number of classes which provide: - - Fast, but low level, 2D graphics functionality - Convenient sound effect loading, management and playback - - - diff --git a/src/documentation/haiku_book/gamekit.xml b/src/documentation/haiku_book/gamekit.xml deleted file mode 100644 index 6e25b276a1..0000000000 --- a/src/documentation/haiku_book/gamekit.xml +++ /dev/null @@ -1,7 +0,0 @@ - - - - The Game Kit - - - diff --git a/src/documentation/haiku_book/howto.xml b/src/documentation/haiku_book/howto.xml deleted file mode 100644 index a8a8474202..0000000000 --- a/src/documentation/haiku_book/howto.xml +++ /dev/null @@ -1,738 +0,0 @@ - - - -]> - - - - Developer Documentation Writing Howto - 2005-10-26 - - - Niels - Reedijk - - - - - - This guide is for Haiku Developers that need to write developer documentation. - - - - - - 1 - 2005-12-23 - nielx - First section about documenting classes on review. - - - - - - Introduction - - - The Haiku project maintains application programming interface (from now on - API) documentation for developers that want to write and port - applications on the platform. The project strives to create and maintain a uniform and - clear book that describes the API, named the Haiku Book. - - - - The tool to help structure and format the Haiku Book is Docbook. Docbook is originally - a SGML-based text that was developed for separating structure - and formatting in the age of digital publication. Docbook is basically a document type - definition (from now on DTD) that provides a standard that can be - used to generate a whole slew of output formats. The Haiku project chose this format - so that the documentation can be transformed into several output formats without any - effort. Furthermore, the format is is widely used and understood, and is structured by - the well-known XML standard. - - - - This document is written to prescribe a set of conventions so that the Haiku Book will - become a coherent whole. It also serves as a manual for those that are unfamiliar with - docbook, who will probably at times feel 'lost'. However, beginners using this manual - when documenting their classes, you will be able to generate proper docbook and create - a structure that fits in with the rest. Since the DTD contains over - three hundred elements, this document also selects which elements are used in our - documentation. Thus, this manual is also helpful to those more familiar with docbook. - - - - At the moment there is only one section finished. - - - - - Documenting Classes - - - This chapter will outline all the formal docbook structure for documenting classes, - as well as give hints on the content of the documentation. - - - - If you are documenting a class that hasn't been documented before, please read - the section on documenting a new class. If you are - working on an existing class, you can proceed to the - formal formatting. - - - - Documenting a new class - - - This section describes the rules on where to place the documentation of a new - class. It discusses - the place in the file hierchy, and how to hook it into the existing documentation. - Please read through this desciption carefully if you are adding a new class. For - those that are merely modifying classes that already exist, you can skip this - section. - - - - Where do I place my file? - - - When writing the documentation for a new class, you will create a new file. - This file needs to be placed in the hierchy in the subversion repository, that - is located at src/documentation/haiku_book/. This - directory contains a set of subdirectories that correspond with the class - division the Haiku project uses. You place your file in the subdirectory that - corresponds to the kit the class belongs to. - - - - - How do I name my file? - - - The naming of the file, consistent with header and source naming, consists - of the class name without the B - prefix and with the xml extension. For example, the - BList class would have the List.xml - documentation file. - - - - - What should be the initial contents of the file? - - - The minimal required content for the file is a line that is required by the - XML standard. Furthermore, you'll have to "open" a new - section (and close it), and you'll have to add a title. For example, the - BList class has the following bare minimum: - - - -<?xml version="1.0" encoding="UTF-8"?> - -<sect2 id="blist"> - <title>BList</title> -</sect2> - - - - Please note the following. The sect2 element, like other - sect elements, has the element id. This - id contains the classname in lowercase, including the B-prefix. - For notes on the XML formatting style, please see elsewhere in this document. - - - - - How do I hook in the file into the generated documentation? - - - If you have created the file and put it in the subdirectory that's appropriate - for the kit it belongs to, it's time to hook it into the generated documents. - The way to do this is by opening the api.xml file that's - located in that same subdirectory. Hooking in is a two-step process. First, you - create an entity in the doctype declaration that refers to the content of the - file that describes the class, secondly you refer to that entity in the body of - the document. - - - - The first step involves adding a line at the top of the file in the doctype - declaration. In clase of BList, the following has been - done. - - - -<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - -<!ENTITY list SYSTEM "List.xml"> - -]> - - - - The line with the ENTITY in it, is the one that you need to - recreate for your own file. There are things you need to adapt. First of all, - you need to adapt list to reflect the name of the file in - lowercase, since entities are lowercase by convention. Secondly, you need - to change the filename it refers too. Please make sure you've got the case - right! - - - - Please note that the inclusions are by convention in alphabetical order. So - make sure the new line is at the proper spot. - - - - The second step is calling the entity in the body. For example in the support - kit: - - - -<sect1 id="supportapi"> - <title>Support Kit API</title> - - &list; -</sect1> - - - - The main body of the api.xml file consists of a list of - entities. You place your entity in the list (on a new line). Please remember - that entities are refered to by prefixing the name with - & and postfixing - ;. Please note that this also should be in - alphabetical order by convention. - - - - - - Formal formatting of a class - - - Thersomee are formal requirements for class documentation to be consistent with - the rest of the API documentation. This section will explain in - what order things should be documented, what the formal structural markup - for methods is and what sections are required. - - - - What elements should be in class documentation? - - - This sections describes the order in which things should be described. It - will touch a little bit of the docbook elements used in the larger structure. It - will not describe how you should structure the individual methods. That's for - the next section. - - - - We can distinguish roughly three parts. First of all, we've got the class - summary. This includes a formal block with useful information. Secondly, - we document the constructors and destructors. Thirdly, we describe the static - members that the class might have. Then we describe - the member functions. Finally we describe the operators that are overloaded. - Note that any section can be left out if it's not applicable. For example, the - BList class doesn't have actual overloaded operators, - thus that section is not in the actual documentation. The following example - gives a rough outline of the BList documentation. - - - -<sect2 id="blist"> -<title>BList</title> - -<itemizedlist> - <listitem><para><emphasis>Derived from:</emphasis> none</para></listitem> - <listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/List.h</filename></para></listitem> - <listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem> -</itemizedlist> - -... summary comes here ... - -<bridgehead renderas="sect2">Constructors and Destructors</bridgehead> - -... constructors come here ... - -<bridgehead renderas="sect2">Static Functions</bridgehead> - -... member functions come here ... - -<bridgehead renderas="sect2">Member Functions</bridgehead> - -... member functions come here ... - -<bridgehead renderas="sect2">Operators</bridgehead> - -... operators would come here ... - - - - Class Summary - - - The first part of the class description is the summary. In the example - above it runs from <title>BList</title> to - the first <bridgehead>. There is an obligatory - <itemizedlist>. This list contains three elements: - the class it is derived from, the location it is declared in and the - library you need to link to. - - - - Note that every item in the <itemizedlist> begins - with <listitem>, which also happens to be the - final tags. The item is started with the tag <para>. - The labels to every piece of data is put inside an - <emphasis> block, including the semicolon! There's - a space between the endtag and the actual value. - - - - - The value of the first item, Derived from:, is either a - classname, or none. If it is a class, make sure you link - to it using the entity available. For example, if your class is derived - from BList, use &BList;. - This generates a nice crosslink within the documentation. - - - - The value of the second item, Declared in:, is wrapped - inside a <filename> tag. You refer to the path - relative to the header subdirectory in the Haiku - source tree. - - - - The value of the third item, Library:, is also wrapped - inside a <filename> tag. Stating the name of the - library suffices. The example can be found in libbe.so. - - - - - After that obligatory block, you can write a summary. This section won't - go into details of what good summaries contain (and what they don't). - Please remember to wrap every paragraph into a set of - <para> tags. Also note that if you link to methods - inside your class, that you use the appopriate entities. So if I want to - link to AddItem of my class, I use - &BList_AddItem;. - - - - - Constructor and Destructor - - - The second part focusses on constructors and the - destructor, and the third on the actual members. The second section starts - after the first <bridgehead> with the label - Constructors and Destructors. See for example the - BList constructors and destructors: - - - -<bridgehead renderas="sect2">Constructors and Destructors</bridgehead> - -<sect3 id="blist_constructor"> - <title>BList()</title> - - <constructorsynopsis> - <methodname>BList</methodname> - <methodparam><type>int32</type><parameter>count</parameter><initializer>20</initializer></methodparam> - </constructorsynopsis> - - <constructorsynopsis> - <methodname>BList</methodname> - <methodparam><modifier>const</modifier><type>BList &amp;</type><parameter>list</parameter></methodparam> - </constructorsynopsis> - - ... Description of the constructors here ... -</sect3> - -<sect3 id="blist_destructor"> - <title>~BList()</title> - - <destructorsynopsis> - <methodname>~BList</methodname> - </destructorsynopsis> - - ... Description of the destructor here ... -</sect3> - - - - First of all, the <bridgehead> element is an - element that instructs the stylesheet that transforms the docbook to an - output format to place a header in the same style as the header of the - section (hence the renderas="sect2" attribute). Because - of hierchial reasons, we don't actually want to start a new section. A - similar <bridgehead> is used as the second header - for the member functions. - - - - As you might notice, the BList has two constructors - and one destructor. The constructors are bundled together in the - <sect3> element with the id - blist_constructor. Like every other id, this one is - lowercase. The label must be the full classname in lowercase, an - underscore and the word constructor. The destructor - section is built up in a similar way. The title is the name of the method, - without any of it's arguments. So in case of the constructor, it is - BList(). - - - - As you can see, there is a normal constructor and a copy constructor. The - rule is that the copy constructor should always be places last. If you have - overloaded constructors, the order is somewhat at will, but please take as - guiding principle that it's most logical to order the constructors in order of - the amount of parameters (so from most complex to simpler). Feel free to - drop this order if your argument in the description or the synopsis requires - another order of constructors. - - - - The actual descriptions of the constructors are embedded in a - <constructorsynopsis> element. The destructor - is embedded in a <destructorsynopsis> element. - These are special variations of the <methodsynopsis> - construction, for they don't require a return type. They do follow the rest of - the rules of the <methodsynopsis> construction. - - - - For a more detailed description about the - <methodsynopsis> construction, see - . Some guiding lines on writing descriptions - will occur in a later section, but please note that you should wrap them in - <para> tags. - - - - Static and Member documentation - - - Static documentation starts under the second - <bridgehead> with the label - Static Functions. The member functions start under - Member Functions. These <bridgehead> - have the same properties as the one the one used with the constructors. - Note that either section can be left out if they are not applicable. - - - - In order to illustrate some of the principles, here's a piece of the - documentation for the BList class: - - - -<bridgehead renderas="sect2">Member Functions</bridgehead> -<sect3 id="blist_additem"> - <title>AddItem()</title> - - <methodsynopsis> - <type>bool</type><methodname>AddItem</methodname> - <methodparam><type>void *</type><parameter>item</parameter></methodparam> - <methodparam><type>int32</type><parameter>index</parameter></methodparam> - </methodsynopsis> - - <methodsynopsis> - <type>bool</type><methodname>AddItem</methodname> - <methodparam><type>void *</type><parameter>item</parameter></methodparam> - </methodsynopsis> - - ... Here comes documentation for this (or these) method(s)... -</sect3> - -<sect3 id="blist_countitems"> - <title>CountItems()</title> - - <methodsynopsis> - <type>int32</type><methodname>CountItems</methodname><modifier>const</modifier> - </methodsynopsis> - - ... Here comes documentation for this (or these) method(s)... -</sect3> - -<sect3 id="blist_removeitem"> - <title>RemoveItem()</title> - - <methodsynopsis> - <type>bool</type><methodname>RemoveItem</methodname> - <methodparam><type>void *</type><parameter>item</parameter></methodparam> - </methodsynopsis> - - <methodsynopsis> - <type>void *</type><methodname>RemoveItem</methodname> - <methodparam><type>int32</type><parameter>index</parameter></methodparam> - </methodsynopsis> - - <methodsynopsis> - <type>bool</type><methodname>RemoveItems</methodname> - <methodparam><type>int32</type><parameter>index</parameter></methodparam> - <methodparam><type>int32</type><parameter>count</parameter></methodparam> - </methodsynopsis> - - ... Here comes documentation for this (or these) method(s)... -</sect3> - -<sect3 id="blist_removeitems"> - <title>RemoveItems()</title> - - <para>See &BList_RemoveItem;</para> -</sect3> - - - - The first thing that's important is that every distinct method has it's own - <sect3>. The id attribute is build up of the - lowercase full classname, an underscore and the name of the method, also in - lowercase. There are no braces present. The title of the section is the - name of the method with proper casing, followed by closed braces (without a - space before or between them). Note that all the sections are ordered - alphabetically. - - - - Let's take the CountItems() method as an example. - We notice that the prototype of the function is encapsulated in a - <methodsynopsis> construction. This construction - is discussed in more detail in . If a - method is overloaded, like the AddItem() - method, both the prototypes are given. - - - - Important is the fact that multiple methods can be grouped together. For - instance, the documentation for the RemoveItems() - method is included in the documentation of the singular - RemoveItem(). Thus that prototype is listed in - that location. Please note that it still is obligatory to create a separate - section for RemoveItems(), as you can see in the - example. You don't have to put anything in that section, besides the title - and one <para> with the contents See - and the entity that refers to the method where it is documented. - - - - If you group different methods together, the rule is that they should be in - alphabetical order. If you have overloaded method, take the guideline that - they should be reverse ordered in complexity (complex first, simple later). - The guideline is that this should be done by the amount of parameters, but - if your method or documentation would be clearer by another order, you are - allowed to order them as you like. - - - - After the method synopsis is done, you add the documentation. This section - doesn't discuss the guidelines for writing good documentation. Please refer - to another section for that. Do remember that you need to wrap it between - <para> elements. - - - - - Operators - - - Operator overloading is quite common in the Haiku API - and as such it should be documented. The original Be Book gave operators - a special treatment, and we've decided to reproduce it in the Haiku Book as - well. As noted before, if there are any overloaded operators, they are placed - under a special bridgehead with the label Operators. In - essence, operators aren't so different from methods in the sense that - they both contain a methodsynopsis and a description, - but there are some oddities you need to be aware of. See the example - from the BString class: - - - -<bridgehead renderas="sect2">Operators</bridgehead> -<sect3 id="bstring_operator_assignment"> - <title>= (assignment)</title> - - <methodsynopsis> - <type>BString &amp;</type><methodname>operator=</methodname> - <methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam> - </methodsynopsis> - - <methodsynopsis> - <type>BString &amp;</type><methodname>operator=</methodname> - <methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam> - </methodsynopsis> - - - - The first thing to note is how the id in the - sect3 tag is built up. It starts with the lowercase - classname, an underscore, the word operator an - underscore, and a short description of what the operator does. Later this - section I'll try to present some standard operator descriptions which you - should follow as much as possible. - - - - The next thing is the title. The title is built up of the operator (here the - =), and a description of what it does, lowercase in parenthesis. - - - - Last thing of note in this example is that the methodname - is quite literally the name of the method in the header file. This wraps up - the conventions we use for individual overloaded operators. - - - - More interesting is the order of the operators. The following list shows - the order and the common descriptions of the overloaded operators. - - - - = (assignment) - += (append) - << (stream; formatted append) - [] (indexing) - ==, !=, <, >, <=, >= (comparison) - - - - This list is far from complete. As more classes are documented, more - possiblities will be described. Do try to combine the comparison operators - into one block: they share the same features. Also, if your description - contains a space, substitute it for an underscore in the id - parameter of the sect3 tag. - - - - - - How do I write a proper methodsynopsis? - - - Docbook provides several tools for properly documenting methods. It is - important that you use the correct markup, to create a uniform format. A - synopsis lives inside a methodsynopsis block. So open - and close the block and follow the following list of instructions step by step - to document the methods properly. - - - - - Open the block with <methodsynopsis>. Then put in - a newline and jump in one tab. - - - - If the method has a modifier, the first element of - the line is this modifier. Modifiers are virtual, - inline and static. Enclose the modifier - in a modifier block. - - - - For the return type, there are two options. - - - - In case the method doesn't return a value, please use the tag - <void/>. Note the trailing slash! - - - - In case of a return type, please enclose the return type in a - type block. Note that if you've got - const BList * as a return type, that complete segment - is the return type. So the const is also considered a - part of the return type! - - - - The name of the method is next, which should be enclosed in a - methodname block. Use the proper - capitalisation. Note that you don't need to include the trailing - parenthesis. The stylesheet will do this when it processes the block. - - - - If the method has arguments, put every argument on a new line. Put the line - between <methodparam> tags. - - - - If the argument has a modifier, use the modifier - tag. Modifiers are const and mutable. - Notice that const is considered a modifier - in arguments, as opposed to const in return - values. The logic is that you may pass a non-const object - in, and the modifier just tells you how the method is going to handle it, as - opposed to the return value which always is the const object when it has - that modifier. - - - - Put the type of the argument between type tags. Note - that if the argument is a pointer or a reference, that the asterix (*) and - the ampersand (&) are included between the tags. Pay attention - to the fact that XML requires your ampersand to be - encoded like this: &amp;. - - - - Enclose the the name of the parameter between parameter - tags. Note that the name of the parameter is obligatory. Use the original - name that is in the header file. - - - - If the argument has an initialiser, put the value between the - initializer tags. Note that you should not put the = in - front of it. - - - - Don't forget to end each line with </methodparam>! - - - - The last thing you need to be aware of is whether or not the method is - modified by a trailing const, or if the method is a pure - virtual. If so, you need to append either - <modifier>const</modifier> or - <modifier>= 0</modifier>. Please note the - space between the = and the 0 in the - syntax for the pure virtuals. The location of this modifier - depends on whether or not the method has arguments. If it doesn't have - any arguments, just append it to the single line you've written. If there are - arguments, put this on a newline after the last argument. - - - - And of course, the <methodsynopsis> ends with - /<methodsynopsis>. - - - - - Please note that constructors and destructors have a slightly different syntax. - Instead of the <methodsynopsis> tags, they are - enclosed in the <constructorsynopsis> or - <destructorsynopsis> tags. And they don't have return - types. The rest of the rules that are described here are valid. - - - - - - &license; - diff --git a/src/documentation/haiku_book/interface/intro.xml b/src/documentation/haiku_book/interface/intro.xml deleted file mode 100644 index 8a0c37a96c..0000000000 --- a/src/documentation/haiku_book/interface/intro.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - - - Introduction - - - The Interface Kit is the core of the window drawing, clicking-dragging, typing, scrolling, GUI world of Haiku. Any application which wants to use any widget will use this set of classes to manage their windows and respond to user/system feedback. - - diff --git a/src/documentation/haiku_book/interfacekit.xml b/src/documentation/haiku_book/interfacekit.xml deleted file mode 100644 index fc06a4bf36..0000000000 --- a/src/documentation/haiku_book/interfacekit.xml +++ /dev/null @@ -1,7 +0,0 @@ - - - - The Interface Kit - - - diff --git a/src/documentation/haiku_book/kernel/intro.xml b/src/documentation/haiku_book/kernel/intro.xml deleted file mode 100644 index 26f668f4b1..0000000000 --- a/src/documentation/haiku_book/kernel/intro.xml +++ /dev/null @@ -1,25 +0,0 @@ - - - - - Introduction - - - Kernel Kit is about classes needed to interact with the kernel. Information about it is available in several topics : - - - - - helps to perform tasks. - - - helps to communicate between threads. - - - helps to synchronize threads. - - - diff --git a/src/documentation/haiku_book/kernel/ports.xml b/src/documentation/haiku_book/kernel/ports.xml deleted file mode 100644 index 52c838ed29..0000000000 --- a/src/documentation/haiku_book/kernel/ports.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - -Ports - - diff --git a/src/documentation/haiku_book/kernel/sems.xml b/src/documentation/haiku_book/kernel/sems.xml deleted file mode 100644 index 0ea3911145..0000000000 --- a/src/documentation/haiku_book/kernel/sems.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - -Semaphores - - diff --git a/src/documentation/haiku_book/kernel/threads.xml b/src/documentation/haiku_book/kernel/threads.xml deleted file mode 100644 index ee8cb0e79e..0000000000 --- a/src/documentation/haiku_book/kernel/threads.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - -Threads - - diff --git a/src/documentation/haiku_book/kernelkit.xml b/src/documentation/haiku_book/kernelkit.xml deleted file mode 100644 index e9cdeefc28..0000000000 --- a/src/documentation/haiku_book/kernelkit.xml +++ /dev/null @@ -1,12 +0,0 @@ - - - -The Kernel Kit - - - - - - - - diff --git a/src/documentation/haiku_book/mail/intro.xml b/src/documentation/haiku_book/mail/intro.xml deleted file mode 100644 index 236c0f3fb6..0000000000 --- a/src/documentation/haiku_book/mail/intro.xml +++ /dev/null @@ -1,18 +0,0 @@ - - - - - Introduction - - The Mail Kit encompasses all email activities on Haiku, providing means for, but not limited to: - - Sending and receiving of email - Interfacing for the manipulation of email messages and attachments - Manipulating email account information - - - - diff --git a/src/documentation/haiku_book/mailkit.xml b/src/documentation/haiku_book/mailkit.xml deleted file mode 100644 index 18b23e5c3f..0000000000 --- a/src/documentation/haiku_book/mailkit.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - -The Mail Kit - - - - diff --git a/src/documentation/haiku_book/media/intro.xml b/src/documentation/haiku_book/media/intro.xml deleted file mode 100644 index 8bf240dd63..0000000000 --- a/src/documentation/haiku_book/media/intro.xml +++ /dev/null @@ -1,17 +0,0 @@ - - - - - Introduction - - - The Media Kit controls the heart of the Haiku media playback, recording and transformation. It contains classes in two main areas: - - Application: The consumption and production of media. Encoding, decoding and playback. - Node: Direct manipulation of media nodes which process the media - - - diff --git a/src/documentation/haiku_book/mediakit.xml b/src/documentation/haiku_book/mediakit.xml deleted file mode 100644 index 2bb7d4fd96..0000000000 --- a/src/documentation/haiku_book/mediakit.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - The Media Kit - - - - diff --git a/src/documentation/haiku_book/midi/intro.xml b/src/documentation/haiku_book/midi/intro.xml deleted file mode 100644 index b0e5def492..0000000000 --- a/src/documentation/haiku_book/midi/intro.xml +++ /dev/null @@ -1,48 +0,0 @@ - - - - - Introduction - - - The Midi Kit is the API that implements support for generating, processing, and - playing music in MIDI format. MIDI, which - stands for 'Musical Instrument Digital Interface', is a well-established - standard for representing and communicating musical data. - - - - The BeOS comes with two different, but compatible Midi Kits. This documentation - focuses on the "new" Midi Kit, or midi2 as we like to call it, that was - introduced with BeOS R5. The old kit, which we'll refer to as midi1, is more - complete than the new kit, but less powerful. - - - - Both kits let you create so-called MIDI endpoints, but the endpoints from midi1 - cannot be shared between different applications. The midi2 kit solves that - problem, but unlike midi1 it does not include a General MIDI softsynth, nor - does it have a facility for reading and playing Standard MIDI Files. Don't - worry: both kits are compatible and you can mix-and-match them in your - applications. - - - - The main differences between the two kits: - - Instead of one BMidi object that both produces and consumes events, we have - BMidiProducer and BMidiConsumer. - Applications are capable of sharing MIDI producers and consumers with other - applications via the centralized Midi Roster. - Physical MIDI ports are now sharable without apps "stealing" events from each - other. - Applications can now send/receive raw MIDI byte streams (useful if an - application has its own MIDI parser/engine). - Channels are numbered 0..15, not 1..16 - Timing is now specified in microseconds instead of milliseconds. - - - diff --git a/src/documentation/haiku_book/midi/midi1.xml b/src/documentation/haiku_book/midi/midi1.xml deleted file mode 100644 index 4b9e31df84..0000000000 --- a/src/documentation/haiku_book/midi/midi1.xml +++ /dev/null @@ -1,66 +0,0 @@ - - - - - The Old Midi 1 Kit - - The old Midi Kit, or midi1 for short, goes all the way back to DR8, when the - BeOS only ran on BeBoxen. Fortunately for us, it is pretty well documented: - - Midi - Kit chapter in the online Be Book - Midi - Kit section of the old Be Developer Library - Be Newsletter Volume 1, Issue 49 - Introduces the MIDI synth - Be Newsletter Volume 1, Issue 52 - Follow-up on issue 49 - Be Newsletter Volume 1, Issue 91 - How to use BSynth - Be Newsletter Volume 1, Issue 102 - Axe sample code - Be Newsletter Volume 1, Issue 104 - How to use BMidiPort - Be Newsletter Volume 2, Issue 23 - EdMidi sample code - Be Newsletter Volume 2, Issue 37 - How to use the MIDI synth - Be Newsletter Volume 3, Issue 37 - Whistle sample code - - - - To summarize, there are four basic MIDI classes: - - BMidi is the base class for most other classes from the Midi Kit. - BMidiPort can talk to a MIDI hardware port. - BMidiStore can read, write, and perform Standard MIDI files. - BMidiText is a debugging aid that dumps MIDI messages to stdout - - - - - The following classes let you use the Midi Kit's General MIDI synthesizer: - - BSynth controls the synthesizer. - BMidiSynth connects a BMidi object to the synth. - BMidiSynthFile connects a MIDI file to the synth - BSamples lets you access the synth's sound data stream - - - - To make MIDI data stream through your application, you create a "network" of - BMidi-derived objects that send and receive MIDI messages. - - - - The old Midi Kit is slowly fading into obscurity. You may want to use the - MIDI 2 Kit instead. Also note that the Haiku implementation - of the kit sometimes behaves differently than the one from BeOS R5 or what - the BeBook says, but usually for the better ;-) - - - - Especially the synth classes are not completely functional, but enough to - play back General MIDI tunes. They should be backwards compatible with the - majority of BeOS MIDI applications. Not all methods of BSynth, BMidiSynth, - and BMidiSynthFile are implemented because some of them are rather obscure. - BSamples is a complete no-op; in other words, with the Haiku Midi Kit - you cannot push waveform data into the output stream of the softsynth. - - diff --git a/src/documentation/haiku_book/midi/midi2.xml b/src/documentation/haiku_book/midi/midi2.xml deleted file mode 100644 index d3d80fcf89..0000000000 --- a/src/documentation/haiku_book/midi/midi2.xml +++ /dev/null @@ -1,362 +0,0 @@ - - - -The Midi 2 Kit - - - Concepts - - - A brief overview of the elements that comprise the Midi Kit: - - Endpoints. This is what the Midi Kit is all about: sending MIDI messages - between endpoints. An endpoint is like a MIDI In or MIDI Out socket on your - equipment; it either receives information or it sends information. Endpoints - that send MIDI events are called \b producers; the endpoints that receive those - events are called \b consumers. An endpoint that is created by your own - application is called \b local; endpoints from other applications are \b - remote. You can access remote endpoints using \b proxies. - - Filters. A filter is an object that has a consumer and a producer - endpoint. It reads incoming events from its consumer, performs some operation, - and tells its producer to send out the results. In its current form, the Midi - Kit doesn't provide any special facilities for writing filters. - - Midi Roster. The roster is the list of all published producers and - consumers. By publishing an endpoint, you allow other applications to talk to - it. You are not required to publish your endpoints, in which case only your own - application can use them. - - Midi Server. The Midi Server does the behind-the-scenes work. It - manages the roster, it connects endpoints, it makes sure that endpoints can - communicate, and so on. The Midi Server is started automatically when BeOS - boots, and you never have to deal with it directly. Just remember that it runs - the show. - - libmidi. The BMidi* classes live inside two shared libraries: libmidi.so - and libmidi2.so. If you write an application that uses old Midi Kit, you must - link it to libmidi.so. Applications that use the new Midi Kit must link to - libmidi2.so. If you want to mix-and-match both kits, you should also link to - both libraries. - - - -
The concepts captured in an image - - - - - An overview of the MIDI kit. - -
- - - - Midi Kit != Media Kit - - - Be chose not to integrate the Midi Kit into the Media Kit as another media - type, mainly because MIDI doesn't require any of the format negotiation that - other media types need. Although the two kits look similar -- both have a - "roster" for finding or registering "consumers" and "producers" -- there are - some very important differences. - - - - The first and most important point to note is that BMidiConsumer and - BMidiProducer in the Midi Kit are NOT directly analogous to BBufferConsumer and - BBufferProducer in the Media Kit! In the Media Kit, consumers and producers are - the data consuming and producing properties of a media node. A filter in the - Media Kit, therefore, inherits from both BBufferConsumer and BBufferProducer, - and implements their virtual member functions to do its work. - - - - In the Midi Kit, consumers and producers act as endpoints of MIDI data - connections, much as media_source and media_destination do in the Media Kit. - Thus, a MIDI filter does not derive from BMidiConsumer and BMidiProducer; - instead, it contains BMidiConsumer and BMidiProducer objects for each of its - distinct endpoints that connect to other MIDI objects. The Midi Kit does not - allow the use of multiple virtual inheritance, so you can't create an object - that's both a BMidiConsumer and a BMidiProducer. - - - - This also contrasts with the old Midi Kit's conception of a BMidi object, which - stood for an object that both received and sent MIDI data. In the new Midi Kit, - the endpoints of MIDI connections are all that matters. What lies between the - endpoints, i.e., how a MIDI filter is actually structured, is entirely at your - discretion. - - - - Also, rather than use token structs like media_node to make connections via the - MediaRoster, the new kit makes the connections directly via the BMidiProducer - object. - - - - - Remote and local objects - - - The Midi Kit makes a distinction between remote and local MIDI objects. You can - only create local MIDI endpoints, which derive from either BMidiLocalConsumer - or BMidiLocalProducer. Remote endpoints are endpoints that live in other - applications, and you access them through BMidiRoster. - - - - BMidiRoster only gives you access to BMidiEndpoints, BMidiConsumers, and - BMidiProducers. When you want to talk to remote MIDI objects, you do so through - the proxy objects that BMidiRoster provides. Unlike BMidiLocalConsumer and - BMidiLocalProducer, these classes do not provide a lot of functions. That is - intentional. In order to hide the details of communication with MIDI endpoints - in other applications, the Midi Kit must hide the details of how a particular - endpoint is implemented. - - - - So, what can you do with remote objects? Only what BMidiConsumer, - BMidiProducer, and BMidiEndpoint will let you do. You can connect objects, get - the properties of these objects -- and that's about it. - - - - - Creating and Destroying Objects - - - The constructors and destructors of most midi2 classes are private, which mean - you cannot directly create them using the C++ new operator, on the - stack, or as globals. Nor can you delete them. Instead, these - objects are obtained through BMidiRoster. The only two exceptions to this rule - are BMidiLocalConsumer and BMidiLocalProducer. These two objects may be - directly created and subclassed by developers. - - - - - Reference Counting - - - Each MIDI endpoint has a reference count associated with it, so that the Midi - Roster can do proper bookkeeping. When you construct a BMidiLocalProducer or - BMidiLocalConsumer endpoint, it starts with a reference count of 1. In - addition, BMidiRoster increments the reference count of any object it hands to - you as a result of BMidiRoster::NextEndpoint() or - BMidiRoster::FindEndpoint(). Once the count hits - 0, the endpoint will be deleted. - - - - This means that, to delete an endpoint, you don't call the delete - operator directly; instead, you call BMidiEndpoint::Release(). To balance this call, - there's also an BMidiEndpoint::Acquire(), in case you have two disparate parts of - your application working with the endpoint, and you don't want to have to keep - track of who needs to Release() the endpoint. - - - - When you're done with any endpoint object, you must Release() it. This is true - for both local and remote objects. Repeat after me: Release() when you're done. - - - - - MIDI Events - - - To make some actual music, you need to BMidiProducer::Connect() - your consumers to your producers. Then you tell the producer to - "spray" MIDI events to all the connected consumers. The consumers are notified - of these incoming events through a set of hook functions. - - - - The Midi Kit already provides a set of commonly used spray functions, such as - BMidiLocalProducer::SprayNoteOn(), BMidiLocalProducer::SprayControlChange(), and so - on. These correspond one-to-one with the message types from the MIDI spec. You - don't need to be a MIDI expert to use the kit, but of course some knowledge of - the protocol helps. If you are really hardcore, you can also use the - BMidiLocalProducer::SprayData() to send raw MIDI events to - the consumers. - - - - At the consumer side, a dedicated thread invokes a hook function for every - incoming MIDI event. For every spray function, there is a corresponding hook - function, e.g. BMidiLocalConsumer::NoteOn() and - BMidiLocalConsumer::ControlChange(). The hardcore MIDI - fanatics among you will be pleased to know that you can also tap into the - BMidiLocalConsumer::Data() hook and get your hands dirty with - the raw MIDI data. - - - - - Time - - The spray and hook functions accept a bigtime_t parameter named "time". This - indicates when the MIDI event should be performed. The time is given in - microseconds since the computer booted. To get the current tick measurement, - you call the system_time() function from the Kernel Kit. - - - - If you override a hook function in one of your consumer objects, it should look - at the time argument, wait until the designated time, and then perform its - action. The preferred method is to use the Kernel Kit's - snooze_until() function, which sends the consumer thread to sleep - until the requested time has come. (Or, if the time has already passed, returns - immediately.) - - - - Like this: - - void MyConsumer::NoteOn( - uchar channel, uchar note, uchar velocity, bigtime_t time) - { - snooze_until(time, B_SYSTEM_TIMEBASE); - ...do your thing... - } - - - - - If you want your producers to run in real time, i.e. they produce MIDI data - that needs to be performed immediately, you should pass time 0 to the spray - functions (which also happens to be the default value). Since time 0 has - already passed, snooze_until() returns immediately, and the - consumer will process the events as soon as they are received. - - - - To schedule MIDI events for a performance time that lies somewhere in the - future, the producer must take into account the consumer's latency. Producers - should attempt to get notes to the consumer by or before - (scheduled_performance_time - latency). The time argument is still the - scheduled performance time, so if your consumer has latency, it should snooze - like this before it starts to perform the events: - - snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); - - - - - Note that a typical producer sends out its events as soon as it can; unlike a - consumer, it does not have to snooze. - - - - - Other Timing Issues - - - Each consumer object uses a Kernel Kit port to receive MIDI events from - connected producers. The queue for this port is only 1 message deep. This means - that if the consumer thread is asleep in a snooze_until(), it will - not read its port. Consequently, any producer that tries to write a new event - to this port will block until the consumer thread is ready to receive a new - message. This is intentional, because it prevents producers from generating and - queueing up thousands of events. - - - - This mechanism, while simple, puts on the producer the responsibility for - sorting the events in time. Suppose your producer sends three Note On events, - the first on t + 0, the second on t + 4, and the third on t + 2. This last - event won't be received until after t + 4, so it will be two ticks too late. If - this sort of thing can happen with your producer, you should somehow sort the - events before you spray them. Of course, if you have two or more producers - connected to the same consumer, it is nearly impossible to sort this all out - (pardon the pun). So it is not wise to send the same kinds of events from more - than one producer to one consumer at the same time. - - - - The article Introduction to MIDI, Part 2 in Haiku - Newsletter 36 describes this problem in more detail, and provides a - solution. Go read it now! - - - - - Writing a Filter - - - A typical filter contains a consumer and a producer endpoint. It receives - events from the consumer, processes them, and sends them out again using the - producer. The consumer endpoint is a subclass of BMidiLocalConsumer, whereas - the producer is simply a BMidiLocalProducer, not a subclass. This is a common - configuration, because consumers work by overriding the event hooks to do work - when MIDI data arrives. Producers work by sending an event when you call their - member functions. You should hardly ever need to derive from BMidiLocalProducer - (unless you need to know when the producer gets connected or disconnected, - perhaps), but you'll always have to override one or more of - BMidiLocalConsumer's member functions to do something useful with incoming - data. - - - - Filters should ignore the time argument from the spray and hook functions, and - simply pass it on unchanged. Objects that only filter data should process the - event as quickly as possible and be done with it. Do not - snooze_until() in the consumer endpoint of a filter! - - - - - API Differences - - - As far as the end user is concerned, the OpenBeOS Midi Kit is mostly the same - as the BeOS R5 kits, although there are a few small differences in the API - (mostly bug fixes): - - BMidiEndpoint::IsPersistent() always returns false. - The B_MIDI_CHANGE_LATENCY notification is now properly sent. The Be kit - incorrectly set be:op to B_MIDI_CHANGED_NAME, even though the rest of the - message was properly structured. - If creating a local endpoint fails, you can still Release() the object - without crashing into the debugger. - - - - - - See Also - - - More about the Midi Kit: - - Be Newsletter Volume 3, Issue 47 - Motor Mix sample code - Be Newsletter Volume 4, Issue 3 - Overview of the new kit - Haiku - Newsletter 33, Introduction to MIDI, Part 1 - Haiku - Newsletter 36, Introduction to MIDI, Part 2 - Sample code and other goodies at the - OpenBeOS Midi Kit team page - - - - - Information about MIDI in general: - - MIDI Manufacturers Association - MIDI Tutorials - MIDI Specification - Standard MIDI File Format - Jim Menard's MIDI Reference - - - - - - diff --git a/src/documentation/haiku_book/midi/midi2api.xml b/src/documentation/haiku_book/midi/midi2api.xml deleted file mode 100644 index af748cd6fe..0000000000 --- a/src/documentation/haiku_book/midi/midi2api.xml +++ /dev/null @@ -1,63 +0,0 @@ - - - - - - - - - -BMidiRoster"> -FindEndpoint()"> -NextEndpoint()"> -Register()"> -Unregister()"> -StartWatching()"> - -BMidiEndpoint"> -Name()"> -SetName()"> -ID()"> -Register()"> -Unregister()"> -IsProducer()"> -IsConsumer()"> -IsRemote()"> -IsLocal()"> -IsPersistent()"> -IsValid()"> -Acquire()"> -Release()"> -SetProperties()"> -GetProperties()"> - -BMidiLocalConsumer"> -BMidiLocalConsumer"> -Timeout"> - -BMidiLocalProducer"> - -BMidiProducer"> -Connect()"> -Disconnect()"> - -BMidiConsumer"> -Latency()"> - -]> - - - Midi 2 Kit API - - &midi2defs; - &midi2roster; - &midi2endpoint; - &midi2consumer; - &midi2producer; - &midi2localconsumer; - &midi2localproducer; - - diff --git a/src/documentation/haiku_book/midi/midi2concepts.png b/src/documentation/haiku_book/midi/midi2concepts.png deleted file mode 100644 index 2278a4d53b..0000000000 Binary files a/src/documentation/haiku_book/midi/midi2concepts.png and /dev/null differ diff --git a/src/documentation/haiku_book/midi/midi2consumer.xml b/src/documentation/haiku_book/midi/midi2consumer.xml deleted file mode 100644 index 282ea1424e..0000000000 --- a/src/documentation/haiku_book/midi/midi2consumer.xml +++ /dev/null @@ -1,72 +0,0 @@ - - - - BMidiConsumer - - - A consumer is an object that knows how to deal with incoming MIDI events. A - consumer can be connected to multiple producers at the same time. There is no - way to find out which producers are connected to this consumer just by looking - at the &BMidiConsumer; object; you will have to consult &BMidiRoster; for that. - - - - A &BMidiConsumer; either represents a local consumer, i.e. a class extending from - &BMidiLocalConsumer;, or is a proxy for a remote object published by another app. - - - - Latency() - - - bigtime_t - Latency - const - - - - The latency is measured in microseconds. Producers should attempt to get MIDI - events to this consumer by (when - latency). You do this by subtracting - the latency from the performance time when you spray the events (provided that - you spray these events ahead of time, of course). - - - - You cannot set the latency on a &BMidiConsumer;, only on a - &BMidiLocalConsumer;. - - - - The latency issue gets slightly more complicated when multiple endpoints are - chained together, as in the following picture: - - -+-------+ +-------------+ +-------+ -| | | | | | -| prodA |---->| consB prodB |---->| consC | -| | | | | | -+-------+ +-------------+ +-------+ -appA appB (filter) appC - - - - - Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply - reports 100ms, then prodA will schedule its events for (t - 100), which is - really 200ms too late. (Of course, producers send out their events as soon as - possible, so depending on the load of the system, everything may work out just - fine.) - - - - ConsB should report the latency of the consumer that is hooked up to its - output, consC, in addition to its own latency. In other words, the full - downstream latency. So, the reported latency in this case would be 300ms. This - also means that appB should change the latency of consB when prodB makes or - breaks a connection, and when consC reports a latency change. (If multiple - consumers are connected to prodB, you should take the slowest one.) - Unfortunately, the Midi Kit provides no easy mechanism for doing any of this, - so you are on your own here. - - - diff --git a/src/documentation/haiku_book/midi/midi2defs.xml b/src/documentation/haiku_book/midi/midi2defs.xml deleted file mode 100644 index da672f140d..0000000000 --- a/src/documentation/haiku_book/midi/midi2defs.xml +++ /dev/null @@ -1,285 +0,0 @@ - - - - Midi Defs - - - The Midi2Defs.h defines a series of constants that are used throughout - the Kit. - - - - Channel message masks - - - - - - B_NOTE_OFF - 0x80 - - - B_NOTE_ON - 0x90 - - - B_KEY_PRESSURE - 0xa0 - - - B_CONTROL_CHANGE - 0xb0 - - - B_PROGRAM_CHANGE - 0xc0 - - - B_CHANNEL_PRESSURE - 0xd0 - - - B_PITCH_BEND - 0xe0 - - - -
- - - System Messages - - - - - - B_SYS_EX_START - 0xf0 - - - B_MIDI_TIME_CODE - 0xf1 - - - B_SONG_POSITION - 0xf2 - - - B_SONG_SELECT - 0xf3 - - - B_CABLE_MESSAGE - 0xf5 - - - B_TUNE_REQUEST - 0xf6 - - - B_SYS_EX_END - 0xf7 - - - B_TIMING_CLOCK - 0xf8 - - - B_START - 0xfa - - - B_CONTINUE - 0xfb - - - B_STOP - 0xfc - - - B_ACTIVE_SENSING - 0xfe - - - B_SYSTEM_RESET - 0xff - - - -
- - - Controller numbers - - - - - - B_MODULATION - 0x01 - - - B_BREATH_CONTROLLER - 0x02 - - - B_FOOT_CONTROLLER - 0x04 - - - B_PORTAMENTO_TIME - 0x05 - - - B_DATA_ENTRY - 0x06 - - - B_MAIN_VOLUME - 0x07 - - - B_MIDI_BALANCE - 0x08 - - - B_PAN - 0x0a - - - B_EXPRESSION_CTRL - 0x0b - - - B_GENERAL_CTRL_1 - 0x10 - - - B_GENERAL_CTRL_2 - 0x11 - - - B_GENERAL_CTRL_3 - 0x12 - - - B_GENERAL_CTRL_4 - 0x13 - - - B_SUSTAIN_PEDAL - 0x40 - - - B_PORTAMENTO - 0x41 - - - B_SOSTENUTO - 0x42 - - - B_SOFT_PEDAL - 0x43 - - - B_HOLD_2 - 0x45 - - - B_GENERAL_CTRL_5 - 0x50 - - - B_GENERAL_CTRL_6 - 0x51 - - - B_TEMPO_CHANGE - 0x51 - - - B_GENERAL_CTRL_7 - 0x52 - - - B_GENERAL_CTRL_8 - 0x53 - - - B_EFFECTS_DEPTH - 0x5b - - - B_TREMOLO_DEPTH - 0x5c - - - B_CHORUS_DEPTH - 0x5d - - - B_CELESTE_DEPTH - 0x5e - - - B_PHASER_DEPTH - 0x5f - - - B_DATA_INCREMENT - 0x60 - - - B_DATA_DECREMENT - 0x61 - - - B_RESET_ALL_CONTROLLERS - 0x79 - - - B_LOCAL_CONTROL - 0x7a - - - B_ALL_NOTES_OFF - 0x7b - - - B_OMNI_MODE_OFF - 0x7c - - - B_OMNI_MODE_ON - 0x7d - - - B_MONO_MODE_ON - 0x7e - - - B_POLY_MODE_ON - 0x7f - - - -
- - - BMidiOp - - - - B_MIDI_NO_OP - B_MIDI_REGISTERED - B_MIDI_UNREGISTERED - B_MIDI_CONNECTED - B_MIDI_DISCONNECTED - B_MIDI_CHANGED_NAME - B_MIDI_CHANGED_LATENCY - B_MIDI_CHANGED_PROPERTIES - - -
- diff --git a/src/documentation/haiku_book/midi/midi2endpoint.xml b/src/documentation/haiku_book/midi/midi2endpoint.xml deleted file mode 100644 index ce003ddf7d..0000000000 --- a/src/documentation/haiku_book/midi/midi2endpoint.xml +++ /dev/null @@ -1,520 +0,0 @@ - - - - BMidiEndpoint - - - The MidiEndpoint.h file defines the &BMidiEndpoint;, - which is the baseclass for all MIDI endpoints. - - - - &BMidiEndpoint; is the abstract base class that represents either a producer or - consumer endpoint. It may be used to obtain the state, name, properties, or - system-wide ID of the object. &BMidiEndpoint; also provides the ability to change - the name and properties of endpoints that were created locally. - - - - Remember, you cannot call the destructor of &BMidiEndpoint; and its subclasses - directly. Endpoint objects are destructed automatically when their reference - count drops to zero. If necessary, the destructor of a local endpoint first - breaks off any connections and &BMidiEndpoint_Unregister;'s the endpoint before it is - deleted. However, for good style and bonus points you should really - &BMidiProducer_Disconnect; and &BMidiEndpoint_Unregister; the object - yourself and not rely on the destructor to do this. - - - Member Functions - - - Name() - - - constchar * - Name - const - - - - Returns the name of the endpoint. - - - - The function never returns NULL. If you created a local endpoint by passing a - NULL name into its constructor (or passing no name, which is the same thing), - then &BMidiEndpoint_Name; will return an empty string, not NULL. - - - - See also &BMidiEndpoint_SetName;. - - - - - SetName() - - - SetName - constchar *name - - - - Changes the name of the endpoint. - - - - Names don't have to be unique, but it is recommended that you give any - endpoints you publish meaningful and unique names, so users can easily - recognize what each endpoint does. There is no limit to the size of endpoint - names. - - - - Even though you can call this function on both remote and local objects, you - are only allowed to change the names of local endpoints; &BMidiEndpoint_SetName; - calls on remote endpoints are ignored. - - - - name The new name. If you pass NULL, the name simply won't be changed. - - - - See also &BMidiEndpoint_Name;. - - - - - ID() - - - int32 ID const - - - - Returns the ID of the endpoint. - - - - An ID uniquely identifies an endpoint in the system. The ID is a signed 32-bit - number that is assigned by the Midi Server when the endpoint is created. (So - even if a local endpoint is not published, it still has a unique ID.) Valid IDs - range from 1 to 0x7FFFFFFF, the largest value an int32 can have. 0 and negative - values are not valid IDs. - - - - - IsProducer() - - - bool IsProducer const - - - - Determines whether this endpoint is a &BMidiProducer;. - - - - If it is, you can use a dynamic_cast to convert this object into a producer: - - -if (endp->IsProducer()) -{ - BMidiProducer* prod = dynamic_cast <BMidiProducer*>(endp); - .... -} - - - - - - IsConsumer() - - - bool IsConsumer const - - - - Determines whether this endpoint is a &BMidiConsumer;. - - - - If it is, you can use a dynamic_cast to convert this object into a consumer: - -if (endp->IsConsumer()) -{ - BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp); - .... -} - - - - - - IsRemote() - - - bool IsRemote const - - - - Determines whether this endpoint is a proxy for a remote object. - - - - An endpoint is "remote" when it is created by another application. Obviously, - the remote object is &BMidiEndpoint_Register;'ed as well, otherwise you would not be able to - see it. - - - - - IsLocal() - - - bool IsLocal const - - - - Determines whether this endpoint represents a local object. - - - - An endpoint is "local" when it is created by this application; in other words, - a &BMidiLocalConsumer; or &BMidiLocalProducer;. - - - - - IsPersistent() - - - bool IsPersistent const - - - - Not used. - - - - The purpose of this function is unclear, and as a result it doesn't do anything - in the Haiku implementation of the Midi Kit. - - - - Always returns false. - - - - - IsValid() - - - bool IsValid const - - - - Determines whether the endpoint still exists - - - - Suppose you obtained a proxy object for a remote endpoint by querying the - &BMidiRoster;. What if the application that published this endpoint quits, or - less drastically, &BMidiEndpoint_Unregister;'s that endpoint? Even though you still have a - &BMidiEndpoint; proxy object, the real endpoint no longer exists. You can use - &BMidiEndpoint_IsValid; to check for this. - - - - Don't worry, operations on invalid objects, such as &BMidiEndpoint_GetProperties;, will - return an error code (typically B_ERROR), but not cause a crash. Local objects - are always are considered to be valid, even if you did not &BMidiEndpoint_Register; them. - (The only time a local endpoint is not valid is when there was a problem - constructing it.) - - - - If the application that created the remote endpoint crashes, then there is no - guarantee that the Midi Server immediately recognizes this. In that case, - &BMidiEndpoint_IsValid; may still return true. Eventually, the stale endpoint will be removed - from the roster, though. From then on, &BMidiEndpoint_IsValid; correctly returns false. - - - - - Acquire() - - - status_t Acquire - - - - Increments the endpoint's reference count - - - - Each &BMidiEndpoint; has a reference count associated with it, so that - &BMidiRoster; can do proper bookkeeping. &BMidiEndpoint_Acquire; increments this reference - count, and &BMidiEndpoint_Release; decrements it. Once the count reaches zero, the endpoint - is deleted. - - - - When you are done with the endpoint, whether local or remote, you should - always &BMidiEndpoint_Release; it! - - - - Upon construction, local endpoints start with a reference count of 1. Any - objects you obtain from &BMidiRoster; using the NextXXX() or FindXXX() functions - have their reference counts incremented in the process. If you forget to call - &BMidiEndpoint_Release;, the objects won't be properly cleaned up and you'll make a fool out - of yourself. - - - - After you &BMidiEndpoint_Release; an object, you are advised not to use it any further. If - you do, your app will probably crash. That also happens if you &BMidiEndpoint_Release; an - object too many times. - - - - Typically, you don't need to call &BMidiEndpoint_Acquire;, unless you have two disparate - parts of your application working with the same endpoint, and you don't want to - have to keep track of who needs to &BMidiEndpoint_Release; the endpoint. Now you simply have - both of them release it. - - - - Always returns B_OK. - - - - See also &BMidiEndpoint_Release;. - - - - - Release() - - - status_t Release - - - - Decrements the endpoint's reference count. - - - - Always returns B_OK. - - - - See also &BMidiEndpoint_Acquire; - - - - - Register() - - - status_t Register - - - - Publishes the endpoint on the roster. - - - - MIDI objects created by an application are invisible to other applications - until they are published. To publish an object use the &BMidiEndpoint_Register; - method. The corresponding &BMidiEndpoint_Unregister; method will cause an object to - once again become invisible to remote applications. - - - - &BMidiRoster; also has &BMidiRoster_Register; and &BMidiRoster_Unregister; methods. You may also use - those methods to publish or hide your endpoints; both do the same thing. - - - - Although it is considered bad style, calling &BMidiEndpoint_Register; on local endpoints that - are already registered won't mess things up. The Midi Server will simply ignore - your request. Likewise for &BMidiEndpoint_Unregister;'ing more than once. Attempts to - &BMidiEndpoint_Register; or &BMidiEndpoint_Unregister; remote endpoints will fail, of course. - - - - If you are &BMidiRoster_StartWatching; watching, you will - not receive notifications for any local endpoints you register or - unregister. Of course, other applications will be notified about your - endpoints. - - - - Existing connections will not be broken when an object is unregistered, but - future remote connections will be denied. When objects are destroyed, they - automatically become unregistered. - - - - Returns B_OK on success, or a negative error code (typically B_ERROR) if - something went wrong. - - - - See also &BMidiEndpoint_Unregister;. - - - - - Unregister() - - - status_t Unregister - - - - Hides the endpoint from the roster. - - - - See also &BMidiEndpoint_Register;. - - - - - SetProperties() - - - status_t SetProperties - constBMessage *properties - - - - Changes the properties of the endpoint. - - - - Endpoints can have properties, which is any kind of information that might be - useful to associate with a MIDI object. The properties are stored in a - BMessage. - - - - Usage example: - - -BMessage props; -if (endpoint->GetProperties(&props) == B_OK) -{ - ...add data to the message... - endpoint->SetProperties(&props); -} - - - - - - You are only allowed to call &BMidiEndpoint_SetProperties; on a local object. - - - - Properties should follow a protocol, so different applications will know how to - read each other's properties. The current protocol is very limited -- it only - allows you to associate icons with your endpoints. Be planned to publish a more - complete protocol that included additional information, such as vendor/model - names, copyright/version info, category, etc., but they never got around to it. - - - - Large Icon Property - - - - - - property - Large (32x32) icon - - - field name - "be:large_icon" - - - field type - 'ICON' - - - -
- - - Small Icon Property - - - - - - property - Small (16x16) ico - - - field name - "be:mini_icon" - - - field type - 'MICN' - - - -
- - - The MidiUtil package (downloadable from the Haiku website) contains a number - of convenient functions to associate icons with endpoints, so you don't have to - write that code all over again. - - - - See also &BMidiEndpoint_GetProperties;. - - - - - GetProperties() - - - status_t GetProperties - BMessage *properties - const - - - - Reads the properties of the endpoint - - - - Usage example: - - -BMessage props; -if (endpoint->GetProperties(&props) == B_OK) -{ - ...examine the contents of the message... -} - - - - - Note that &BMidiEndpoint_GetProperties; overwrites the contents of your BMessage. - - - - See also &BMidiEndpoint_SetProperties; - - - diff --git a/src/documentation/haiku_book/midi/midi2localconsumer.xml b/src/documentation/haiku_book/midi/midi2localconsumer.xml deleted file mode 100644 index 8492e056fd..0000000000 --- a/src/documentation/haiku_book/midi/midi2localconsumer.xml +++ /dev/null @@ -1,381 +0,0 @@ - - - - BMidiLocalConsumer - - - A consumer endpoint that is created by your own application - - - - If you want to create a consumer that reacts to MIDI events, you should - subclass BMidiLocalConsumer. - - - - Each local consumer has its own thread that receives and dispatches the MIDI - events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to - a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so - on. Calls to these hook functions are serialized -- they will never have to be - re-entrant. They also should not be called from outside the thread that is - invoking them. - - - - Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer - doesn't provide default implementations for them, so you don't have to call a - hook's default implementation if you override it. For complete control, you can - also override Data(). - - - - Most hook functions take a channel argument. Even though MIDI channels are - really numbered 1 through 16, the hook functions work with channels 0 through - 15. The performance time for the event is specified in microseconds relative to - the system time base. A performance time that is 0 (or really any time in the - past) means "play as soon as possible". See the - for more information about timing and consumers. - - - - The thread driving the consumer's events is a very high priority real time - thread. Events should be handled as quickly as possible (not counting - snoozing). If non-time-critical computation is needed it may be wise to queue - events up for a lower priority thread to handle them external to the main event - thread. - - - - BMidiLocalConsumer() - - - BMidiLocalConsumer - constchar *nameNULL - - - - Creates a new local consumer endpoint. - - - - The new endpoint is not visible to other applications until you &BMidiRoster_Register; it. - - - - You can tell the constructor what the name of the new consumer will be. If you - pass NULL (or use the default argument), then the consumer's name will be an - empty string. It won't be NULL, since endpoint names cannot be NULL. - - - - There is no guarantee that the endpoint will be successfully created. For - example, the Midi Server may not be running. Therefore, you should always call - IsValid() after creating a new endpoint to make sure that everything went okay. - If not, &BMidiEndpoint_Release; the object to reclaim memory and abort gracefully. - - - - - MyConsumer* cons = new MyConsumer(...); - if (!cons->IsValid()) - { - cons->Release(); - ...exit gracefully... - } - - - - - - SetLatency() - SetLatencybigtime_tlatency - - - Changes the published latency of the consumer. - - - - - - GetProducerID() - int32GetProducerID - - - Returns the ID of the producer that most recently sent a MIDI event to - this consumer. - - - - You can call this from one of the hooks to determine which producer the event - came from. - - - - - SetTimeout() - SetTimeoutbigtime_twhenvoid *data - - - Requests that the &BMidiLocalConsumer_Timeout; hook will be called at some point - - - - This method asks the consumer thread to call the &BMidiLocalConsumer_Timeout; hook as soon as - possible after the timeout expires. For every call to SetTimeout(), the - &BMidiLocalConsumer_Timeout; hook is only called once. Note: the term "timeout" may be a little - misleading; the hook will always be called, even if events are received - in the mean time. Apparently, this facility is handy for dealing with early - events. - - - - - Note that the event thread blocks on the consumer's port as long as no events - arrive. By default no timeout is set, and as a result the thread blocks - forever. Your call to SetTimeout() doesn't change this. The new timeout value - will go into effect the next time the thread tries to read from the port, i.e. - after the first event has been received. If no event ever comes in, the - &BMidiLocalConsumer_Timeout; hook will never be called. This also means that you cannot cancel a - timeout once you have set it. To repeat, calling SetTimeout() only takes effect - after at least one new event has been received. - - - - Parameters: - - when An absolute time that's - measured against the system clock. - data A pointer to a "cookie" that - you can pass along to &BMidiLocalConsumer_Timeout;. The data is not copied, so - you must ensure that the pointer remains valid until &BMidiLocalConsumer_Timeout; is - called. You typically delete the data inside &BMidiLocalConsumer_Timeout;. - - - - - - Timeout() - virtualTimeoutvoid *data - - - Hook function that is called per your own request. - - - - See Also - - - - - Data() - virtualDatauchar *datasize_tlengthboolatomicbigtime_ttime - - - Invoked when raw MIDI is received - - - - What the default implementation of Data() does depends on the value of atomic. - If atomic is true, the data received comprises a single MIDI event; i.e. one - status byte followed by the appropriate number of data bytes and nothing else. - In this case, Data() calls the event-specific hook function that corresponds to - that status byte. This optimization is used by the Midi Kit to allow faster - dispatch of events generated by the specific Spray functions from - BMidiLocalProducer. - - - - If atomic is false, Data() ignores the MIDI event. If you want a consumer to - handle non-atomic events, you have to override Data() and program this - yourself. In that case, you probably also want to call the default - implementation to handle the "normal" MIDI events. - - - - Data() is rarely overridden, but you can override it if you want to. If you do, - remember that the data buffer is owned by the Midi Kit. Do not attempt to - modify or free it, lest you wish to be laughed at by other developers. - - - - Parameters: - - data the MIDI event data - length byte size of the data buffer - atomic whether the data buffer contains - a single complete MIDI event - time the requested performance time of the event - - - - - See Also - - - - - NoteOff() - virtualNoteOffucharchannelucharnoteucharvelocitybigtime_ttime - - - Invoked when a Note Off event is received - - - - See Also - - - - - NoteOn() - virtualNoteOnucharchannelucharnoteucharvelocitybigtime_ttime - - - Invoked when a Note On event is received - - - - See Also - - - - - KeyPressure() - virtualKeyPressureucharchannelucharnoteucharpressurebigtime_ttime - - - Invoked when a Polyphonic Pressure (Aftertouch) event is received - - - - See Also - - - - - ControlChange() - virtualControlChangeucharchannelucharcontrolNumberucharcontrolValuebigtime_ttime - - - Invoked when a Controller Change event is received - - - - See Also - - - - - ProgramChange() - virtualProgramChangeucharchannelucharprogramNumberbigtime_ttime - - - Invoked when a Program Change event is received - - - - See Also - - - - - ChannelPressure() - virtualChannelPressureucharchannelucharpressurebigtime_ttime - - - Invoked when a Channel Pressure event is received - - - - See Also - - - - - PitchBend() - virtualPitchBenducharchannelucharlsbucharmsbbigtime_ttime - - - Invoked when a Pitch Bend event is received - - - - See Also - - - - - SystemExclusive() - virtualSystemExclusivevoid *datasize_tlengthbigtime_ttime - - - Invoked when a System Exclusive event is received - - - - The data does not include the sysex start and end control bytes (0xF0 and 0xF7), - only the payload of the sysex message. - - - - The data belongs to the Midi Kit and is only valid for the duration of this - event. You may not modify or free it. - - - - See Also - - - - - SystemCommon() - virtualSystemCommonucharstatusuchardata1uchardata2bigtime_ttime - - - Invoked when a System Common event is received. - - - - Not all data bytes are used for all common events. Unused bytes are set to 0. - - - - See Also - - - - - SystemRealTime() - virtualSystemRealTimeucharstatusbigtime_ttime - - - Invoked when a Real Time event is received - - - - See Also - - - - - TempoChange() - virtualTempoChangeint32beatsPerMinutebigtime_ttime - - - Invoked when a Tempo Change event is received - - - - See Also - - - - - AllNotesOff() - virtualAllNotesOffbooljustChannelbigtime_ttime - - - Not used - - - diff --git a/src/documentation/haiku_book/midi/midi2localproducer.xml b/src/documentation/haiku_book/midi/midi2localproducer.xml deleted file mode 100644 index b88bf15f25..0000000000 --- a/src/documentation/haiku_book/midi/midi2localproducer.xml +++ /dev/null @@ -1,403 +0,0 @@ - - - - BMidiLocalProducer - - - You create a BMidiLocalProducer if you want your application to send MIDI - events. You use the various spray functions to send events to all connected - consumers. If no consumers are connected to the producer, any calls to the - spray functions are ignored. - - - - Most spray functions accept a channel argument. Even though MIDI channels are - really numbered 1 through 16, the spray functions work with channels 0 through - 15. You can also specify the performance time for the event using the time - argument. Specify 0 (or any time in the past) to perform the event "now", i.e. - as soon as possible. You can also schedule events to be performed in the - future, by passing a time such as system_time() + 5000000, which means 5 - seconds from now. - - - - Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly - ever need to derive a class from BMidiLocalProducer. The only reason for - subclassing is when you need to know when the producer gets connected or - disconnected. - - - - Also unlike consumers, local producers have no thread of control directly - associated with them. If you want to send out the MIDI events from a different - thread, you will have to create one yourself. - - - - BMidiLocalProducer() - - BMidiLocalProducer - constchar *nameNULL - - - Creates a new local producer endpoint. - - - - The new endpoint is not visible to other applications until you Register() it. - - - - You can tell the constructor what the name of the new producer will be. If you - pass NULL (or use the default argument), then the producer's name will be an - empty string. It won't be NULL, since endpoint names cannot be NULL. - - - - There is no guarantee that the endpoint will be successfully created. For - example, the Midi Server may not be running. Therefore, you should always call - &BMidiEndpoint_IsValid; after creating a new endpoint to make sure that everything went okay. - If not, &BMidiEndpoint_Release; the object to reclaim memory and abort gracefully. - - - - - BMidiLocalProducer *prod = new BMidiLocalProducer(...); - if (!prod->IsValid()) - { - prod->Release(); - ...exit gracefully... - } - - - - - - Connected() - virtualConnectedconstBMidiConsumer *cons - - Invoked when a new consumer is connected to this producer - - - - Although typical notifications (i.e. from BMidiRoster's "watching" facility) - are only sent if it is some other app that is performing the operation, - Connected() is also called if you are making the connection yourself. - - - - If you override this hook, you don't have to call the default implementation, - because that does nothing. - - - - cons The newly connected consumer. The reference count of the consumer - object is not increased, so you should not Release() it. However, if you want - to keep track of the consumer beyond this function, you should first Acquire() - it, and Release() it when you are done. - - - - See Also - - - - - Disconnected() - virtualDisconnectedconstBMidiConsumer *cons - - - Invoked when a consumer is disconnected from this producer. - - - - See Also - - - - - SprayData() - SprayDatavoid *datasize_tlengthboolatomicfalsebigtime_ttime0const - - - Sends raw MIDI data downstream to all connected consumers - - - - Typically you won't have to call SprayData(); the other spray functions will do - just fine. If you do call it, remember that you retain ownership of the data - and that you are responsible for freeing it at some point. (Even though data is - not declared const, the function does not change it.) - - - - With atomic set to false, you can send a MIDI message in segments (perhaps for - a large sysex dump). However, when you do this, you are on your own. The Midi - Kit only tags the data as being non-atomic, but offers no additional support. - The default implementation of BMidiLocalConsumer completely ignores such - events. To handle non-atomic MIDI data, you should override the - BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of - BMidiLocalProducer's other spray functions always send atomic data. - - - - Parameters: - - data the MIDI event data - length byte size of the data buffer - atomic whether the data buffer contains - a single complete MIDI event - time the required performance time of the event - - - - - - SprayNoteOff() - SprayNoteOffucharchannelucharnoteucharvelocitybigtime_ttime0const - - - Sends a Note Off event to all connected consumers - - - - See Also - - - - - SprayNoteOn() - SprayNoteOnucharchannelucharnoteucharvelocitybigtime_ttime0const - - - Sends a Note On event to all connected consumers - - - - See Also - - - - - SprayKeyPressure() - SprayKeyPressureucharchannelucharnoteucharpressurebigtime_ttime0const - - - Sends a Polyphonic Pressure (Aftertouch) event to all connected - consumers. - - - - See Also - - - - - SprayControlChange() - SprayControlChangeucharchannelucharcontrolNumberucharcontrolValuebigtime_ttime0const - - - Sends a Controller Change event to all connected consumers. - - - - See Also and - - - - - - SprayProgramChange() - SprayProgramChangeucharchannelucharprogramNumberbigtime_ttime0const - - - Sends a Program Change event to all connected consumers - - - - See Also - - - - - SprayChannelPressure() - SprayChannelPressureucharchannelucharpressurebigtime_ttime0const - - - Sends a Channel Pressure event to all connected consumers - - - - See also - - - - - SprayPitchBend() - SprayPitchBenducharchannelucharlsbucharmsbbigtime_ttime0const - - - Sends a Pitch Bend event to all connected consumers - - - - See Also - - - - - SpraySystemExclusive() - SpraySystemExclusivevoid *datasize_tlengthbigtime_ttime0const - - - Sends a System Exclusive event to all connected consumers - - - - You retain ownership of the data and are responsible for freeing it. Even - though data is not declared const, the function does not change it. Even though - the amount of data may be quite large, this function always sends sysex - messages as an atomic block of data. - - - - See Also - - - - - SpraySystemCommon() - SpraySystemCommonucharstatusuchardata1uchardata2bigtime_ttime0const - - - Sends a System Common event to the connected consumers - - - - The status byte must be one of the following: - - - System Status - - - - - - - 0xF1 - B_MIDI_TIME_CODE - data1 only - - - 0xF2 - B_SONG_POSITION - data1 and data2 - - - 0xF3 - B_SONG_SELECT - data1 only - - - 0xF5 - B_CABLE_MESSAGE - data1 only - - - 0xF6 - B_TUNE_REQUEST - no data - - - 0xF7 - B_SYS_EX_END - no data - - - -
- - - - See Also - - - - - SpraySystemRealTime() - SpraySystemRealTimeucharstatusbigtime_ttime0const - - - Sends a Real Time event to the connected consumers - - - - The status byte must be one of the following: - - - RealTime Status - - - - - - - 0xF8 - B_TIMING_CLOCK - - - 0xFA - B_START - - - 0xFB - B_CONTINUE - - - 0xFC - B_STOP - - - 0xFE - B_ACTIVE_SENSING - - - 0xFF - B_SYSTEM_RESET - - - -
- - - - Because of their high priority, the MIDI specification allows real time - messages to "interleave" with other MIDI messages. A large sysex dump, for - example, may be interrupted by a real time event. The Midi Kit, however, - doesn't care. If you (or another producer) have just sent a big system - exclusive to a consumer, any following real time message will simply have to - wait until the consumer has dealt with the sysex. - - - - See Also - - - - - SprayTempoChange() - SprayTempoChangeint32beatsPerMinutebigtime_ttime0const - - Sends a Tempo Change event to the connected consumers. - - - - This kind of Tempo Change event is not really part of the MIDI spec, rather - it is an extension from the SMF (Standard MIDI File) format. - - - - See Also - - - diff --git a/src/documentation/haiku_book/midi/midi2producer.xml b/src/documentation/haiku_book/midi/midi2producer.xml deleted file mode 100644 index e3e1b57cba..0000000000 --- a/src/documentation/haiku_book/midi/midi2producer.xml +++ /dev/null @@ -1,140 +0,0 @@ - - - - BMidiProducer - - - Streams MIDI events to connected consumers. - - - - A producer is an object that generate a stream of MIDI events. Each producer - has a list of &BMidiConsumer; objects to which it is connected, and may be asked - to connect to or disconnect from a &BMidiConsumer;. A producer can spray its - events to multiple consumers at the same time. - - - - A &BMidiProducer; either represents a local producer, i.e. a class extending from - &BMidiLocalProducer;, or is a proxy for a remote object published by another app. - - - - Connect() - - - status_t - Connect - constBMidiConsumer * cons - - - - Connects a consumer to this producer. - - - - Establishes a connection between this producer and the specified consumer - endpoint. From now on, any events that this producer sprays will be sent to - that consumer. You may connect multiple consumers to a producer. - - - - Returns B_OK on success, or an error code when the connection could not be - established. If the consumer is a proxy for a remote object and that object no - longer exists, Connect() returns B_ERROR. It also returns B_ERROR if you try to - connect the same producer and consumer more than once. - - - - See Also &BMidiProducer_Disconnect;. - - - - - Disconnect() - - - status_t - Disconnect - constBMidiConsumer * cons - - - - Disconnects a consumer from this producer. - - - - Terminates the connection between this producer and the specified consumer - endpoint. From now on, any events that this producer sprays no longer go to - that consumer. - - - - Returns B_OK on success, or an error code if there was no connection to break - - - - See Also &BMidiProducer_Connect;. - - - - - IsConnected() - - - bool - IsConnected - constBMidiConsumer * cons - const - - - - Determines whether a consumer is connected to this producer. - - - - See Also &BMidiProducer_Connect; and - &BMidiProducer_Disconnect; - - - - - Connections() - - - BList * - Connections - const - - - - Returns a list with all connected consumers. - - - - Returns a BList with pointers to &BMidiEndpoint; objects for all consumers that - are connected to this producer. You can examine the contents of the list as - follows: - - - - -BList *list = prod->Connections(); -for (int32 t = 0; t < list-> CountItems(); ++t) -{ - BMidiEndpoint *endp = (BMidiEndpoint *) list->ItemAt(t); - ...do stuff... - endp->Release(); // yes, here too! -} -delete list; - - - - - Every time you call this function, a new BList is allocated. The caller (that - is you) is responsible for freeing this list. The &BMidiEndpoint; objects in the - list have their reference counts bumped, so you need to &BMidiEndpoint;::&BMidiEndpoint_Release; them before - you delete the list or they will go all leaky on you. - - - diff --git a/src/documentation/haiku_book/midi/midi2roster.xml b/src/documentation/haiku_book/midi/midi2roster.xml deleted file mode 100644 index 531e6d1ec0..0000000000 --- a/src/documentation/haiku_book/midi/midi2roster.xml +++ /dev/null @@ -1,555 +0,0 @@ - - - - BMidiRoster - - - Interface to the system-wide Midi Roster - - - - BMidiRoster allows you to find available MIDI consumer and producer objects. - You can locate these objects using the iterative NextEndpoint(), - NextProducer(), and NextConsumer() methods or by requesting notification - messages to be sent with StartWatching(). Notification messages may contain - object IDs which can be resolved using the FindEndpoint(), FindProducer(), and - FindConsumer() methods. - - - - The constructor and destructor of BMidiRoster are private, which means that you - cannot create or delete your own BMidiRoster objects. Every application can - have only one instance of BMidiRoster, which is automatically created the very - first time you use a Midi Kit function. - - - - You can call BMidiRoster's functions like this: - - producer = FindProducer(someID); - - - Or using the slightly more annoying: - - BMidiRoster *roster = MidiRoster(); - if (roster != NULL) - { - producer = roster->FindProducer(someID); - } - - - - - NextEndpoint() - staticBMidiEndpoint *NextEndpointint32 *id - - - Returns the next endpoint from the roster - - - - The "next endpoint" means: the endpoint with the ID that follows id. So if you - set id to 3, the first possible endpoint it returns is endpoint 4. No endpoint - can have ID 0, so passing 0 gives you the first endpoint. If you pass NULL - instead of an ID, NextEndpoint() always returns NULL. When the function - returns, it sets id to the ID of the endpoint that was found. If no more - endpoints exist, NextEndpoint() returns NULL and id is not changed. - NextEndpoint() does not return locally created endpoints, even if they - are &BMidiEndpoint_Register;'ed. - - - - Usage example: - - int32 id = 0; - BMidiEndpoint *endp; - while ((endp = NextEndpoint(&id)) != NULL) - { - ...do something with endpoint ... - endp->Release(); // don't forget! - } - - - - - Remember that NextEndpoint() bumps the endpoint's reference count, so you - should always BMidiEndpoint::Release() it when you are - done. - - - - - NextProducer() - staticBMidiProducer *NextProducerint32 *id - - - Returns the next producer from the roster - - - - Like &BMidiRoster_NextEndpoint;, but only returns producer endpoints. - - - - See Also and - . - - - - - NextConsumer() - staticBMidiConsumer *NextConsumerint32 *id - - - Returns the next consumer from the roster - - - - Like &BMidiRoster_NextEndpoint;, but only returns consumer endpoints. - - - - See Also and - . - - - - - FindEndpoint() - staticBMidiEndpoint *FindEndpointint32idboollocalOnlyfalse - - - Returns the endpoint with the specified ID - - - - FindEndpoint() will always find any local endpoints created by this - application; they do not have to be published with &BMidiRoster_Register; first. If - localOnly is false, FindEndpoint() also looks at remote endpoints, otherwise - only local endpoints will be resolved. Returns NULL if no such endpoint could - be found. - - - - You should use a dynamic_cast to convert the BMidiEndpoint into a producer or - consumer: - - - - BMidiEndpoint *endp = ...; - BMidiProducer *prod = NULL; - BMidiConsumer *cons = NULL; - - if (endp->IsProducer()) - { - prod = dynamic_cast<BMidiProducer *>(endp); - } - else if (endp->IsConsumer()) - { - cons = dynamic_cast<BMidiConsumer *>(endp); - } - - - - Remember that FindEndpoint() increments the endpoint's reference count, so you - should always &BMidiEndpoint_Release; an endpoint - when you are done with it: - - BMidiEndpoint *endp = FindEndpoint(someID); - if (endp != NULL) - { - ...do stuff with the endpoint... - endp->Release(); - } - - - - - - FindProducer() - staticBMidiProducer *FindProducerint32idboollocalOnlyfalse - - - Finds the producer with the specified ID - - - - Like &BMidiRoster_FindEndpoint;, but only looks for producer endpoints. Returns NULL if no - endpoint with that ID exists, or if that endpoint is not a producer. - - - - See Also and - . - - - - - FindConsumer() - staticBMidiConsumer *FindConsumerint32idboollocalOnlyfalse - - - Finds the consumer with the specified ID - - - - Like &BMidiRoster_FindEndpoint;, but only looks for consumer endpoints. Returns NULL if no - endpoint with that ID exists, or if that endpoint is not a consumer. - - - - See Also and - . - - - - - StartWatching() - staticStartWatchingconstBMessenger *msngr - - - Start receiving notifications from the Midi Roster - - - - When you start watching, BMidiRoster sends you notifications for all currently - published remote endpoints, and all the current connections - between them. (At this point, BMidiRoster does not let you know about - connections between unpublished endpoints, nor does it tell you anything about - your local endpoints, even though they may be published.) - - - - Thereafter, you'll receive notifications any time something important happens - to an object. The application that performs these operations is itself not - notified. The assumption here is that you already know about these changes, - because you are the one that is performing them. - - - - The notifications are BMessages with code B_MIDI_EVENT. You specify the - BMessenger that will be used to send these messages. Each message contains a - field called be:op that describes the type of notification. - - - - The "registered" and "unregistered" notifications are sent when a remote - endpoint Register()'s or Unregister()'s, respectively. You don't receive these - notifications when you register or unregister your local endpoints, but the - other apps will. - - B_MIDI_REGISTERED message structure - - - - - - - be:op - int32 - B_MIDI_REGISTERED - - - - be:id - int32 - ID of the endpoint - - - - be:type - string - "producer" or "consumer" - - - -
- - - B_MIDI_UNREGISTERED message structure - - - - - - - be:op - int32 - B_MIDI_UNREGISTERED - - - - be:id - int32 - ID of the endpoint - - - - be:type - string - "producer" or "consumer" - - - -
- - - - The "connected" and "disconnected" notifications are sent when a consumer - &BMidiProducer_Connect;'s to a producer, or when they - &BMidiProducer_Disconnect;. You will receive these - notifications when any two endpoints connect or disconnect, even if they - are not published. (The purpose of which is debatable.) You won't receive the - notifications if you are the one making the connection, even if both endpoints - are remote. You will be notified when another app connects one of your - published endpoints. - - - B_MIDI_CONNECTED message structure - - - - - - - be:op - int32 - B_MIDI_CONNECTED - - - - be:producer - int32 - ID of the connector - - - - be:consumer - int32 - ID of the connectee - - - -
- - - B_MIDI_DISCONNECTED message structure - - - - - - - be:op - int32 - B_MIDI_DISCONNECTED - - - - be:producer - int32 - ID of the connector - - - - be:consumer - int32 - ID of the connectee - - - -
- - - - The following notifications are sent when an endpoint's attributes are changed. - You receive these notifications only if another application is changing one of - its published endpoints. - - - B_MIDI_CHANGED_NAME message structure - - - - - - - be:op - int32 - B_MIDI_CHANGED_NAME - - - - be:id - int32 - ID of the endpoint - - - - be:type - string - "producer" or "consumer" - - - - be:name - string - the endpoint's new name> - - - -
- - - B_MIDI_CHANGED_LATENCY message structure - - - - - - - be:op - int32 - B_MIDI_CHANGED_LATENCY - - - - be:id - int32 - ID of the endpoint - - - - be:type - string - "producer" or "consumer" - - - - be:latency - int64 - the new latency (microseconds) - - - -
- - - B_MIDI_CHANGED_PROPERTIES message structure - - - - - - - be:op - int32 - B_MIDI_CHANGED_PROPERTIES - - - - be:id - int32 - ID of the endpoint - - - - be:type - string - "producer" or "consumer" - - - - be:properties - BMessage - the new properties - - - -
- - - - Typical usage example: - - void MyView::AttachedToWindow() - { - BMessenger msgr(this); - StartWatching(&msgr); - } - - void MyView::MessageReceived(BMessage *msg) - { - switch (msg->what) - { - case B_MIDI_EVENT: - HandleMidiEvent(msg); - break; - default: - super::MessageReceived(msg); - break; - } - } - - - - - See Also "The possible be:op codes (BMidiOp)". - - - - - StopWatching() - staticStopWatching - - - Stop receiving notifications from the Midi Roster - - - - See Also - - - - - Register() - staticstatus_tRegisterBMidiEndpoint *endp - - - Publishes an endpoint to other applications - - - - Calls BMidiEndpoint's BMidiEndpoint::Register() - method to publish an endpoint, which makes it visible to other applications. - - - - - Unregister() - staticstatus_tUnregisterBMidiEndpoint *endp - - - Hides an endpoint from other applications - - - - Calls BMidiEndpoint's BMidiEndpoint::Unregister() - method to hide a previously published endpoint from other applications - - - - - MidiRoster() - staticBMidiRoster *MidiRoster - - - Returns a pointer to the only instance of BMidiRoster - - - - There is no real reason to use this function, since all BMidiRoster's public - function are static. - - - diff --git a/src/documentation/haiku_book/midikit.xml b/src/documentation/haiku_book/midikit.xml deleted file mode 100644 index 4b3141fe39..0000000000 --- a/src/documentation/haiku_book/midikit.xml +++ /dev/null @@ -1,11 +0,0 @@ - - - - The Midi Kit - - - - - - - diff --git a/src/documentation/haiku_book/network/intro.xml b/src/documentation/haiku_book/network/intro.xml deleted file mode 100644 index 048b947841..0000000000 --- a/src/documentation/haiku_book/network/intro.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - - - Introduction - - The Network Kit encompasses all user network functionality in Haiku, providing both the standard UNIX/POSIX socket implementation along with a number of convenience classes for simple buffering, address operations and endpoint manipulation. - - - diff --git a/src/documentation/haiku_book/networkkit.xml b/src/documentation/haiku_book/networkkit.xml deleted file mode 100644 index 00fc46f79c..0000000000 --- a/src/documentation/haiku_book/networkkit.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - The Network Kit - - - - diff --git a/src/documentation/haiku_book/opengl/intro.xml b/src/documentation/haiku_book/opengl/intro.xml deleted file mode 100644 index 281e060aaf..0000000000 --- a/src/documentation/haiku_book/opengl/intro.xml +++ /dev/null @@ -1,14 +0,0 @@ - - - - - Introduction - - - The OpenGL Kit contains the Haiku OpenGL bindings and the BView subclass BGLView which manages the hardware interface and GL contexts. - - - diff --git a/src/documentation/haiku_book/openglkit.xml b/src/documentation/haiku_book/openglkit.xml deleted file mode 100644 index ef414aa23b..0000000000 --- a/src/documentation/haiku_book/openglkit.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - The OpenGL Kit - - - - diff --git a/src/documentation/haiku_book/storage/intro.xml b/src/documentation/haiku_book/storage/intro.xml deleted file mode 100644 index 8083e05c92..0000000000 --- a/src/documentation/haiku_book/storage/intro.xml +++ /dev/null @@ -1,19 +0,0 @@ - - - - - Introduction - - - The Storage Kit deals with the manipulation, retrieval and creation of filesystem objects. This is enabled by the Haiku implementation of the POSIX filesystem functions (written in C) and a collection of C++ classes which are concerned with areas such as: - - Entries/nodes - Volumes - Queries/Indices - Utility classes - - - diff --git a/src/documentation/haiku_book/storagekit.xml b/src/documentation/haiku_book/storagekit.xml deleted file mode 100644 index 04a15f320e..0000000000 --- a/src/documentation/haiku_book/storagekit.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - The Storage Kit - - - - diff --git a/src/documentation/haiku_book/support/Archivable.xml b/src/documentation/haiku_book/support/Archivable.xml deleted file mode 100644 index 17d8bc8d26..0000000000 --- a/src/documentation/haiku_book/support/Archivable.xml +++ /dev/null @@ -1,60 +0,0 @@ - - - - BArchivable - - - Derived from: none - Declared in: os/support/Archivable.h - Library: libbe.so - - - BArchivable works on archiving and unarchiving BMessages. - - Constructors and Destructors - - BArchivable() - - - BArchivable - - - - BArchivable - BMessage *from - - - - - ~BArchivable() - - - ~BArchivable - - - - Static Functions - - Instantiate() - - - staticBArchivable *Instatiate - BMessage *from - - - - Member Functions - - Archive() - - - virtualstatus_tArchive - BMessage *into - booldeeptrue - const - - - - - - diff --git a/src/documentation/haiku_book/support/Autolock.xml b/src/documentation/haiku_book/support/Autolock.xml deleted file mode 100644 index f5ce67d0b2..0000000000 --- a/src/documentation/haiku_book/support/Autolock.xml +++ /dev/null @@ -1,50 +0,0 @@ - - - - BAutolock - - - Derived from: none - Declared in: os/support/AutoLock.h - Library: libbe.so - - - BAutolock implements easy locking and unlocking using a BLocker or a BLooper object. - - Constructors and Destructors - - BAutolock() - - - inlineBAutolock - BLooper *looper - - - - inlineBAutolock - BLocker *locker - - - - inlineBAutolock - BLocker &locker - - - - - ~BAutoLock() - - - inline~BAutolock - - - - Member Functions - - IsLocked() - - - boolIsLocked - - - diff --git a/src/documentation/haiku_book/support/BlockCache.xml b/src/documentation/haiku_book/support/BlockCache.xml deleted file mode 100644 index ad25b0e8c0..0000000000 --- a/src/documentation/haiku_book/support/BlockCache.xml +++ /dev/null @@ -1,53 +0,0 @@ - - - - BBlockCache - - - Derived from: none - Declared in: os/support/BlockCache.h - Library: libbe.so - - - BBlockCache is used to manage a pool of memory blocks. - - Constructors and Destructors - - BBlockCache() - - - BBlockCache - uint32blockCount - size_tblockSize - uitn32allocationType - - - - - ~BBlockCache() - - - ~BBlockCache - - - - Member Functions - - - Get() - - - void *Get - size_tblockSize - - - - - Save() - - Save - void *pointer - size_tblockSize - - - diff --git a/src/documentation/haiku_book/support/DataIO.xml b/src/documentation/haiku_book/support/DataIO.xml deleted file mode 100644 index 78e9082068..0000000000 --- a/src/documentation/haiku_book/support/DataIO.xml +++ /dev/null @@ -1,53 +0,0 @@ - - - - BDataIO - - - Derived from: none - Declared in: os/support/DataIO.h - Library: libbe.so - - - BDataIO provides a base interface for reading and writing data. - - Constructors and Destructors - - BDataIO() - - - BDataIO - - - - - ~BDataIO() - - - virtual~BDataIO - - - - Member Functions - - Read() - - - virtualssize_tRead - void *buffer - size_tsize - = 0 - - - - - Write() - - - virtualssize_tWrite - constvoid *buffer - size_tsize - = 0 - - - diff --git a/src/documentation/haiku_book/support/Flattenable.xml b/src/documentation/haiku_book/support/Flattenable.xml deleted file mode 100644 index 2c9b258e5c..0000000000 --- a/src/documentation/haiku_book/support/Flattenable.xml +++ /dev/null @@ -1,82 +0,0 @@ - - - - BFlattenable - - - Derived from: none - Declared in: os/support/Flattenable.h - Library: libbe.so - - - BFlattenable is a protocol that classes can implement so that they can be written to a stream of bytes. - - Constructors and Destructors - - ~BFlattenable - - - virtual~BFlattenable - - - - Member Functions - - AllowsTypeCode() - - - virtualboolAllowsTypeCode - type_codecode - = 0 - - - - - Flatten() - - - virtualstatus_tFlatten - void *buffer - ssize_tsize - const= 0 - - - - - FlattenedSize() - - - virtualssize_tFlattenedSizeconst= 0 - - - - - IsFixedSize() - - - virtualboolIsFixedSizeconst= 0 - - - - - TypeCode() - - - virtualtype_codeTypeCodeconst= 0 - - - - - Unflatten - - - virtualstatus_tUnflatten - type_codec - constvoid *buf - ssize_tsize - = 0 - - - - - diff --git a/src/documentation/haiku_book/support/List.xml b/src/documentation/haiku_book/support/List.xml deleted file mode 100644 index 0d4b2c99ab..0000000000 --- a/src/documentation/haiku_book/support/List.xml +++ /dev/null @@ -1,230 +0,0 @@ - - - - BList - - - Derived from: none - Declared in: os/support/List.h - Library: libbe.so - - - BList is a is a simple ordered list of data pointers. - - Constructors and Destructors - - - BList() - - - BList - int32count20 - - - - BList - constBList &list - - - - - ~BList() - - - ~BList - - - - Member Functions - - AddItem() - - - boolAddItem - void *item - int32index - - - - boolAddItem - void *item - - - - - AddList() - - - boolAddList - constBList *list - int32index - - - - boolAddList - constBList *list - - - - - CountItems() - - - int32CountItemsconst - - - - - DoForEach() - - - DoForEach - bool(*func)(void *) - - - - DoForEach - bool(*func)(void *, void *) - void *arg2 - - - - - FirstItem() - - - void *FirstItem()const - - - - - HasItem() - - - boolHasItem - void *item - const - - - - - IndexOf() - - - int32IndexOf - void *item - const - - - - - ItemAt() - - - void *ItemAt - int32index - const - - - - void *ItemAtFast - int32index - const - - - - - ItemAtFast() - - See ItemAt() - - - - Items() - - - void *Itemsconst - - - - - IsEmpty - - - boolIsEmptyconst - - - - - LastItem() - - - void *LastItemconst - - - - - MoveItem() - - - boolMoveItem - int32fromIndex - int32toIndex - - - - - RemoveItem() - - - boolRemoveItem - void *item - - - - void *RemoveItem - int32index - - - - boolRemoveItems - int32index - int32count - - - - - RemoveItems() - - See RemoveItem() - - - - ReplaceItem() - - - boolReplaceItem - int32index - void *newItem - - - - - SortItems() - - - SortItems - int(int (*compareFunc)(const void *, const void *) - - - - - SwapItems() - - - boolSwapItems - int32indexA - int32indexB - - - diff --git a/src/documentation/haiku_book/support/Locker.xml b/src/documentation/haiku_book/support/Locker.xml deleted file mode 100644 index 22b3cbb3b2..0000000000 --- a/src/documentation/haiku_book/support/Locker.xml +++ /dev/null @@ -1,120 +0,0 @@ - - - - BLocker - - - Derived from: none - Declared in: os/support/Locker.h - Library: libbe.so - - - BLocker implements a locking mechanism that can be used to protect multithreaded code. - - Constructors and Destructors - - BLocker() - - - BLocker - - - - BLocker - constchar *name - - - - BLocker - boolbenaphore_style - - - - BLocker - constchar *name - boolbenaphore_style - - - - BLocker - constchar *name - boolbenaphore_style - boolbogus - - - - - ~BLocker() - - - virtual~BLocker - - - - Member Functions - - CountLocks() - - - int32CountLocksconst - - - - - CountLockRequests() - - - int32CountLockRequestsconst - - - - - IsLocked() - - - boolIsLockedconst - - - - - Lock() - - - boolLock - - - - - LockingThread() - - - thread_idLockingThreadconst - - - - - LockWithTimeout() - - - status_tLockWithTimeout - bigtime_ttimeout - - - - - Sem() - - - sem_idSemconst - - - - - Unlock() - - - Unlock - - - - diff --git a/src/documentation/haiku_book/support/MallocIO.xml b/src/documentation/haiku_book/support/MallocIO.xml deleted file mode 100644 index 935be99cdc..0000000000 --- a/src/documentation/haiku_book/support/MallocIO.xml +++ /dev/null @@ -1,105 +0,0 @@ - - - - BMallocIO - - - Derived from:BPositionIO - Declared in: os/support/DataIO.h - Library: libbe.so - - - BMallocIO provides an interface for reading, writing and seeking in a buffer that it maintains itself. - - Constructors and Destructors - - BMallocIO() - - - BMallocIO - - - - - ~BMallocIO() - - - virtual~BMallocIO - - - - Member functions - - Buffer() - - - const void *Bufferconst - - - - - BufferLength() - - - size_tBufferLength()const - - - - - Position() - - - virtualoff_tPositionconst - - - - - ReadAt() - - - virtualssize_tReadAt - off_tposition - void *buffer - size_tsize - - - - - Seek() - - - virtualoff_tSeek - off_tposition - uint32seekMode - - - - - SetBlockSize() - - - SetBlockSize - size_tblockSize - - - - - SetSize() - - - virtualstatus_tSetSize - off_tsize - - - - - WriteAt() - - - virtualssize_tWriteAt - off_tposition - constvoid *buffer - size_tsize - - - \ No newline at end of file diff --git a/src/documentation/haiku_book/support/MemoryIO.xml b/src/documentation/haiku_book/support/MemoryIO.xml deleted file mode 100644 index 879161b20d..0000000000 --- a/src/documentation/haiku_book/support/MemoryIO.xml +++ /dev/null @@ -1,88 +0,0 @@ - - - - BMemoryIO - - - Derived from:BPositionIO - Declared in: os/support/DataIO.h - Library: libbe.so - - - BMemoryIO implements reading, writing and seeking in a data buffer. - - Constructors and Destructors - - BMemoryIO() - - - BMemoryIO - void *data - size_tlength - - - - BMemoryIO - constvoid *data - size_tlength - - - - - ~BMemoryIO() - - - virtual~BMemoryIO - - - - Member functions - - Position() - - - virtualoff_tPositionconst - - - - - ReadAt() - - - virtualssize_tReadAt - off_tposition - void *buffer - size_tsize - - - - - Seek() - - - virtualoff_tSeek - off_tposition - uint32seekMode - - - - - SetSize() - - - virtualstatus_tSetSize - off_tsize - - - - - WriteAt() - - - virtualssize_tWriteAt - off_tposition - constvoid *buffer - size_tsize - - - diff --git a/src/documentation/haiku_book/support/PositionIO.xml b/src/documentation/haiku_book/support/PositionIO.xml deleted file mode 100644 index 60bc2d7465..0000000000 --- a/src/documentation/haiku_book/support/PositionIO.xml +++ /dev/null @@ -1,112 +0,0 @@ - - - - BPositionIO - - - Derived from:BDataIO - Declared in: os/support/DataIO.h - Library: libbe.so - - - BPositionIO provides an interface for reading, writing and seeking within data. - - Constructors and Destructors - - BPositionIO() - - - BPositionIO - - - - - ~BPositionIO() - - - virtual~BPositionIO - - - - Member functions - - GetSize() - - - virtualstatus_tGetSize - off_t *size - - - - - Position() - - - virtualoff_tPositionconst= 0 - - - - - Read() - - - virtualssize_tRead - void *buffer - size_tsize - - - - - ReadAt() - - - virtualssize_tReadAt - off_tposition - void *buffer - size_tsize - = 0 - - - - - Seek() - - - virtualoff_tSeek - off_tposition - uint32seekMode - = 0 - - - - - SetSize() - - - virtualstatus_tSetSize - off_tsize - - - - - Write() - - - virtualssize_tWrite - constvoid *buffer - size_tsize - - - - - WriteAt() - - - virtualssize_tWriteAt - off_tposition - constvoid *buffer - size_tsize - = 0 - - - diff --git a/src/documentation/haiku_book/support/StopWatch.xml b/src/documentation/haiku_book/support/StopWatch.xml deleted file mode 100644 index e87e5cc450..0000000000 --- a/src/documentation/haiku_book/support/StopWatch.xml +++ /dev/null @@ -1,151 +0,0 @@ - - - - BStopWatch - - - Derived from: none - Declared in: os/support/StopWatch.h - Library: libbe.so - - - BStopWatch is a timer class. - - - This class provides method to time events. The interface is designed to behave like a - physical stopwatch. It is especially useful for debugging certain parts of your code, since - it can behave like a 'cheap' profiler. - - - Constructors and Destructors - - BStopWatch() - - - BStopWatch - constchar *name - boolsilentfalse - - - - The constructor creates a clean BStopWatch object. This object - can be given a name. As soon as the object is created, the time - will start ticking away. This class is designed to be usuable as a primitive profiling tool. - If you are profiling your code with this class, pass true as the - silent parameter. Whenever the object is destroyed, information on - the elapsed time will be streamed to standard output. - - - - - ~BStopWatch() - - - virtual~BStopWatch - - - - Destroys the object. If the object was constructed with the parameter - silent set t to false, this destructor will print - information on the elapsed time to standard output. - - - - Member Functions - - ElapsedTime() - - - bigtime_tElapsedTimeconst - - - - This method returns the elapsed time in microseconds since the object was created. If - the object is suspended, the time until the suspend will be returned. - - - - See also: Suspend(). - - - - - Lap - - - bigtime_tLap - - - - This method sets a lap. With the current implementation you are unable to actually - retrieve the timings of the laps. This is only printed to the standard output when the - object is destroyed. Thus making this tool only usuable for use when doing some - profiling. - - - - Please note that the current implementation is limited to 10 laps. The value returned - is the time that has passed since the timer was started (and not the time that has - passed since the last lap). Any lap call beyond the 10th lap will overwrite the last - value. Note that if the timer is suspended, nothing happens and the method will return - 0. - - - - - Name() - - - const char *Nameconst - - - - Returns the name that was given when the object was constructed. - - - - - Reset() - - - Reset - - - - Resets the object: it clears the start time, it clears the stored laps and it restarts - the timer. - - - - - Resume() - - - Resume - - - - Resumes the timer when it is in a suspended state. - - - - See Also: Suspend(). - - - - - Suspend() - - - Suspend - - - - Suspends the timer. - - - - See Also: Resume(). - - - diff --git a/src/documentation/haiku_book/support/String.xml b/src/documentation/haiku_book/support/String.xml deleted file mode 100644 index 4b451a0292..0000000000 --- a/src/documentation/haiku_book/support/String.xml +++ /dev/null @@ -1,663 +0,0 @@ - - - - BString - - - Derived from: none - Declared in: os/support/String.h - Library: libbe.so - - - BString implements a high level string object. - - Constructors and Destructors - - BString() - - - BString - - - - BString - constchar *string - - - - BString - constBString &string - - - - BString - constchar *string - int32maxLength - - - - - ~BString() - - - ~BString() - - - - Member Functions - - Adopt() - - - BString &Adopt - BString &from - - - - BString &Adopt - BString &from - int32length - - - - - Append() - - - BString &Append - constBString &string - - - - BString &Append - const char *string - - - - BString &Append - constBString &string - int32length - - - - BString &Append - constchar *string - int32length - - - - BString &Append - charstring - int32count - - - - - Compare() - - - intCompare - constBString &string - const - - - - intCompare - constchar *string - const - - - - intCompare - constBString &string - int32n - const - - - - intCompare - constchar *string - int32n - const - - - - - CopyInto() - - - BString &CopyInto - BString &into - int32fromOffset - int32length - - - - CopyInto - char *into - int32fromOffset - int32length - - - - - CountChars() - - - int32CountCharsconst - - - - - FindFirst() - - - int32FindFirst - constBString &string - const - - - - int32FindFirst - constchar *string - const - - - - int32FindFirst - constBString &string - int32fromOffset - const - - - - int32FindFirst - constchar *string - int32fromOffset - const - - - - int32FindFirst - charcharacter - const - - - - int32FindFirst - charcharacter - int32fromOffset - const - - - - - FindLast() - - - int32FindLast - constBString &string - const - - - - int32FindLast - constchar *string - const - - - - int32FindLast - constBString &string - int32beforeOffset - const - - - - int32FindLast - constchar *string - int32beforeOffset - const - - - - int32FindLast - charcharacter - const - - - - int32FindLast - charcharacter - int32beforeOffset - const - - - - - ICompare() - - - intICompare - constBString &string - const - - - - intICompare - constchar *string - const - - - - intICompare - constBString &string - int32n - const - - - - intICompare - constchar *string - int32n - const - - - - - IFindFirst() - - - int32IFindFirst - constBString &string - const - - - - int32IFindFirst - constchar *string - const - - - - int32IFindFirst - constBString &string - int32fromOffset - const - - - - int32IFindFirst - constchar *string - int32fromOffset - const - - - - - IFindLast() - - - int32IFindLast - constBString &string - const - - - - int32IFindLast - constchar *string - const - - - - int32IFindLast - constBString &string - int32beforeOffset - const - - - - int32IFindLast - constchar *string - int32beforeOffset - const - - - - - Insert() - - - BString &Insert - constchar *string - int32pos - - - - BString &Insert - constchar *string - int32length - int32pos - - - - BString &Insert - constchar *string - int32fromOffset - int32length - int32pos - - - - BString &Insert - constBString &string - int32pos - - - - BString &Insert - constBString &string - int32length - int32pos - - - - BString &Insert - constBString &string - int32fromOffSet - int32length - int32pos - - - - BString &Inser - charstring - int32count - int32pos - - - - - Length() - - - int32Lengthconst - - - - - MoveInto() - - - BString &MoveInto - BString &into - int32from - int32length - - - - MoveInto - char *into - int32from - int32length - - - - - Prepend() - - - BString &Prepend - constBString &string - - - - BString &Prepend - constchar *string - - - - BString &Prepend - constBString &string - int32length - - - - BString &Prepend - constchar *string - int32length - - - - BString &Prepend - charstring - int32count - - - - - Remove() - - - BString &Remove - int32from - int32length - - - - - RemoveFirst() - - - BString &RemoveFirst - constBString &string - - - - BString &RemoveFirst - constchar *string - - - - - RemoveLast() - - - BString &RemoveLast - constBString &string - - - - BString &RemoveLast - constchar *string - - - - - RemoveAll - - - BString &RemoveAll - constBString &string - - - - BString &RemoveAll - constchar *string - - - - - RemoveSet - - - BString &RemoveSet - constchar *setOfCharsToRemove - - - - - SetTo - - - BString &SetTo - constchar *string - - - - BString &SetTo - constchar *string - int32length - - - - BString &SetTo - constBString &from - - - - BString &SetTo - constBString &from - int32length - - - - BString &SetTo - charstring - int32count - - - - - String() - - - const char *String const - - - - - Truncate() - - - BString &Truncate - int32newLength - boollazytrue - - - - Operators - - = (assignment) - - - BString &operator= - constBString &string - - - - BString &operator= - constchar *string - - - - BString &operator= - charstring - - - - - += (append) - - - BString &operator+= - constBString &string - - - - BString &operator+= - constchar *string - - - - BString &operator+= - constcharcharacter - - - - - <, <=, ==, >, >=, != (comparison) - - - BString &operator< - constBString &string - const - - - - BString &operator< - constchar *string - const - - - - BString &operator<= - constBString &string - const - - - - BString &operator<= - constchar *string - const - - - - BString &operator== - constBString &string - const - - - - BString &operator== - constchar *string - const - - - - BString &operator>= - constBString &string - const - - - - BString &operator>= - constchar *string - const - - - - BString &operator> - constBString &string - const - - - - BString &operator> - constchar *string - const - - - - BString &operator!= - constBString &string - const - - - - BString &operator!= - constchar *string - const - - - diff --git a/src/documentation/haiku_book/support/api.xml b/src/documentation/haiku_book/support/api.xml deleted file mode 100644 index ccdadea312..0000000000 --- a/src/documentation/haiku_book/support/api.xml +++ /dev/null @@ -1,35 +0,0 @@ - - - - - - - - - - - - - - -]> - - - Support Kit API - - &archivable; - &autolock; - &dataio; - &blockcache; - &flattenable; - &list; - &locker; - &mallocio; - &memoryio; - &positionio; - &stopwatch; - &string; - diff --git a/src/documentation/haiku_book/support/intro.xml b/src/documentation/haiku_book/support/intro.xml deleted file mode 100644 index ae606e2ad3..0000000000 --- a/src/documentation/haiku_book/support/intro.xml +++ /dev/null @@ -1,48 +0,0 @@ - - - - - Introduction - - - The Support Kit is an assortment of easy to use classes which allow a programmer to quickly extend their applications without re-writing much common functionality. Many benefits can arrise from using these classes when one starts to extend an application in the future. Functionality includes: - - - Threading utility classes: - - BLocker and BAutoLock - "Thread Local Storage" - - - Archiving and IO: - - BArchivable - BFlattenable - BDataIO - - BPositionIO - - BMemoryIO - BMallocIO - - - - - - - Container classes: - - BBlockCache - BList - BString - - - BStopWatch - Common types and constants - Error codes for all kits - - - diff --git a/src/documentation/haiku_book/supportkit.xml b/src/documentation/haiku_book/supportkit.xml deleted file mode 100644 index bf05cff6f1..0000000000 --- a/src/documentation/haiku_book/supportkit.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - The Support Kit - - - - - diff --git a/src/documentation/haiku_book/translation/intro.xml b/src/documentation/haiku_book/translation/intro.xml deleted file mode 100644 index d964250cf3..0000000000 --- a/src/documentation/haiku_book/translation/intro.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - - - Introduction - - - The Translation Kit gives the user the ability to convert media from one format into a number of target formats. To accomplish this it provides functionality in the form of BTranslatorRoster for the act, management and configuration of the translation and BTranslator for the creation of new translators between additional formats. - - diff --git a/src/documentation/haiku_book/translationkit.xml b/src/documentation/haiku_book/translationkit.xml deleted file mode 100644 index ced2736d13..0000000000 --- a/src/documentation/haiku_book/translationkit.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - The Translation Kit - - - - diff --git a/src/tools/docbook/headersampler/HeaderSampler.pl b/src/tools/docbook/headersampler/HeaderSampler.pl deleted file mode 100644 index 600f97b68a..0000000000 --- a/src/tools/docbook/headersampler/HeaderSampler.pl +++ /dev/null @@ -1,463 +0,0 @@ -#!/bin/perl - -# headerSampler.pl, Copyright (C) 1997, Mizutori Tetsuya -# -# January 7, 1997, February 4, 1997. -# Usage: -# Drag and drop the C++ header files onto this 'header.pl' script - -use integer; -#use strict ('subs','vars'); - -my $gMAC = ( $ENV{'HOME'} =~ /^$/ ); -#if ( $gMAC ) { print "I love Macintosh.\n"; } -my $gScope = ""; -my $gSentence = ""; -my $gDocbookpath = ""; - -# if the command line includes no file list, then prompt the choose dialog. -#push(@ARGV, ChooseFile()) unless defined @ARGV; - -DoMain(); - -ExitToShell(); - -# - -################ -# DoMain -################ - -sub DoMain { - my $filepath; - my $countFiles = 0; - - $filepath = $ARGV[0]; - $gDocbookpath = $ARGV[1]; -# foreach $filepath (@ARGV) { - my ($creator,$type) = GetFileInfo($filepath); - - $countFiles++; - #print "[$countFiles] = ['$creator','$type'] $filepath\n"; - -# skip if the file is not 'TEXT' nor '*.h'. - next if ($type ne 'TEXT'); - next unless ($filepath =~ /\.h$/); - - $gScope = "private:"; - $gSentence = ""; - @gComment = (); - $gIsIgnoring = 0; - - open(IN, $filepath) || die "Can't open '$filepath'"; - while () { - chomp; - HandleTextline(); - } - close IN; -# } -} - - -################ -# HandleTextline -################ - -sub HandleTextline { - -# fetch the commant part if it exists. - if ( m/\/\/.*$/ ) { $gComment[$#gComment + 1] = $&; } - -# ignore the comment part in the line. - s/^(.*)\/\/.*$/$1/; - -# trim the line. - s/^[ \t]+//; - s/[ \t]+$//; - - SWITCH: { - - # skip 'typedef' or 'struct' region. - (/^typedef/ || /^struct/ || /^namespace/) && do { - $gIsIgnoring = 1; - if ( /^namespace.*}$/ ) { $gIsIgnoring = 0; } - last SWITCH; - }; - - # skip this line if it begins with "#ifdef", "#endif", and others. - /^#/ && do { - @gComment = (); - last SWITCH; - }; - - # ignore this line if it begins with "public" and other keywords. - (/^public:/ || /^protected:/ || /^private:/) && do { - $gScope = $_; - $gSentence = ""; - @gComment = (); - last SWITCH; - }; - - # skip this line if it ends with "}???;". - /\}.*;$/ && do { - $gSentence = ""; - @gComment = (); - $gIsIgnoring = 0; - last SWITCH; - }; - - # skip this line if it ends with "}???". for namespace - /\}$/ && do { - $gSentence = ""; - @gComment = (); - $gIsIgnoring = 0; - last SWITCH; - }; - - # test if end of 'typedef' or 'struct' region. - ($gIsIgnoring) && do { - last SWITCH; - }; - - # append this line to my sentence. - do { - $gSentence .= "\t" unless $gSentence =~ /^$/; - $gSentence .= $_; - }; - - # handle my sentence if the line ends with ";". - /;$/ && do { - $_ = $gSentence; - ApplySentence(); - $gSentence = ""; - @gComment = (); - last SWITCH; - }; - } -} - - -################ -# ApplySentence -################ - -sub ApplySentence { -# my ($textline) = @_; - -# eliminate the duplicate spaces to a blank space. - s/[ \t]+/ /g; - -# eliminate the ";" character at the tail end. - s/[ ]*;$//; - - #if ( s/[ ]*const$// ) { PrintFunction(); } # if the function has 'const'modifier. - #elsif ( /\)$/ ) { PrintFunction(); } - if ( /\)/ ) { PrintFunction(); } - #else { PrintVariable(); } - -} - - -################ -# PrintFunction -################ - -sub PrintFunction { -# print a comment. -# my $textline; -# if ( $#gComment >= 0 ) { -# foreach $textline (@gComment) { -# print "\t\t$textline\n"; -# } -# } - - if (! ($gScope =~ /^public/ )) { - return; - } - -# print a scope sign. -#print WhichScope(); - -# print "#$_\n"; - my $functype, $funcname, $funcargs; - -# split line to ( ) parts. - m/[ ]*\([ ]*(.*)[ ]*\)[ ]*([const]*)/; - $funcname = $`; - $funcargs = $1; - $funcconst = $2; - $funcname =~ s/[ ]+$//; - $funcargs =~ s/[ ]+$//; - -# handle func name. - split(/[ ]+/,$funcname); - $funcname = pop(); - $functype = join(' ', @_); - - if ( $funcname =~ /^\*/ ) { - $funcname = $'; - $functype = $functype . " *"; - } - -# handle func arg list. - split(/[ ]*,[ ]*/, $funcargs); - my @args = @_; - for (@args) { - $paramconst = ""; - $paraminit = ""; - if ( /const*/ ) { $paramconst = "const"; } - if ( /[ ]*=[ ]*/ ) { $paraminit = "". $' ."" ; $_ = $`; } # for default value; ex. (short X = 100) - split(/[ ]+/); - $paramname = pop(); - $paramtype = pop(); - if ( $paramname =~ /^\*/ ) { - $paramname = $'; - $paramtype .= " *"; - } - $_ = $paramconst . "" . $paramtype . " " . $paramname . "" . $paraminit; - } - $funcargs = join('', @args); - - if ($functype) { - $_ = $functype; - $funcmod = ""; - if ( s/^virtual[ ]*// ) { - $funcmod .= "virtual" - } - if ( s/^static[ ]*// ) { - if ( $funcmod =~ /^$/ ) { - $funcmod .= " "; - } - $funcmod .= "static" - } - if ($funcmod) { - $funcmod = "" . $funcmod . ""; - } - if ( /^void/ ) { - $functype = $funcmod . "" - } else { - $typeconst = ""; - if ( /^const / ) { $typeconst = "const"; $_ = $'; } - $functype = $funcmod . $typeconst . "" . $_ . "" - } - } - if ($funcconst) { - $funcconst = " " . "" . $funcconst . "" - } - if ($funcargs) { - $funcargs = "" . $funcargs . "" - } else { - $funcargs = "" - } - $_ = $functype . " " . $funcname . " " . $funcargs . $funcconst; - ValidateDocbook(); -# print "FUNC = TYPE($funcname)+NAME($funcname)+ARGS($funcargs)\n"; -# print $funcname . "\t" x CalcTabs($funcname,5) . $functype . "(" . $funcargs . ")"; -# print "\n"; -} - -################ -# ValidateDocbook -################ - -sub ValidateDocbook { - - open(IN2, $gDocbookpath) || die "Can't open '$gDocbookpath'"; - - # we drop every space for the moment - s/[\t ]//g; - - my $line = ""; - my $pattern = $_; - my $found = 0; - my $ignoring = 1; - - while () { - chomp; - s/^[\t ]+//; - s/[\t ]+$//; - s/[\t ]//g; - if ($ignoring) { - if ( m// ) { - $line = $'; - $ignoring = 0; - } - } else { - $line .= $_; - if ( index($line, $pattern) >= 0 ) { - $found = 1; - break; - } - if ( $line =~ /<\/methodsynopsis>/ ) { - $line = ""; - $ignoring = 1; - } - } - } - if ( $found == 0 ) { - $pattern =~ s/\*/ \*/g; - print "".$pattern . "\n" ; - } - close IN2; -} - - -################ -# PrintVariable -################ - -sub PrintVariable { - -# print a scope sign. - print WhichScope(); - -# print "#$_\n"; - my $vartype; - my $varname = $_; - my $varargs = ""; - -# split line to [ ] parts. - if ( m/[ ]*\[[ ]*(.*)[ ]*\][ ]*/ ) { - $varname = $`; - $varargs = $1; - $varname =~ s/[ ]+$//; - $varargs =~ s/[ ]+$//; - } - - split(/[ ]+/,$varname); - my $vartype = join(' ', @_[0..($#_ - 1)]); - my $varname = $_[$#_]; - -# print variable definition - print $vartype . "\t" x CalcTabs($vartype,5). $varname; - if ( $varargs ne "" ) { print "[" . $varargs . "]"; } - -# print a comment. - if ( $#gComment >= 0 ) { - print "\t" x CalcTabs($varname,4); - print join("\t",@gComment); - } - - print "\n"; -} - - -################ -# WhichScope() -################ - -sub WhichScope { -# my ($textline) = @_; - my $key; - my $str; - - SWITCH: { - ( s/^virtual[ ]*// ) && do { $key = "v"; last SWITCH; }; - ( s/^static[ ]*// ) && do { $key = "s"; last SWITCH; }; - do { $key = "."; last SWITCH; } - }; - - SWITCH: { - ($gScope =~ /^public/ ) && do { $str = "=" . $key . "="; last SWITCH; }; - ($gScope =~ /^protected/ ) && do { $str = ">" . $key . ">"; last SWITCH; }; - ($gScope =~ /^private/ ) && do { $str = "(" . $key . ")"; last SWITCH; }; - do { $str = " " . $key . " "; last SWITCH; }; - }; - - return $str . "\t"; -} - - -################ -# StringWidth -################ - -sub StringWidth { - my ($str) = @_; - -# width table of 10-point Geneva font - my %width_table = ( - ' '=> 3, '!'=> 4, '"'=> 5, '#'=> 9, '\$'=> 7, '%'=>10, '&'=> 8, '\''=> 3, - '('=> 6, ')'=> 6, '*'=> 7, '+'=> 8, ','=> 4, '-'=> 7, '.'=> 3, '/'=> 6, - '0'=> 7, '1'=> 7, '2'=> 7, '3'=> 7, '4'=> 7, '5'=> 7, '6'=> 7, '7'=> 7, - '8'=> 7, '9'=> 7, ':'=> 3, ';'=> 4, '<'=> 5, '='=> 7, '>'=> 5, '?'=> 7, - '@'=> 9, 'A'=> 6, 'B'=> 7, 'C'=> 6, 'D'=> 7, 'E'=> 6, 'F'=> 6, 'G'=> 6, - 'H'=> 7, 'I'=> 4, 'J'=> 6, 'K'=> 7, 'L'=> 6, 'M'=> 9, 'N'=> 7, 'O'=> 6, - 'P'=> 7, 'Q'=> 6, 'R'=> 7, 'S'=> 6, 'T'=> 6, 'U'=> 7, 'V'=> 6, 'W'=>10, - 'X'=> 6, 'Y'=> 6, 'Z'=> 6, '['=> 5, '\\'=> 5, ']'=> 5, '^'=> 5, '_'=> 7, - '`'=> 4, 'a'=> 5, 'b'=> 6, 'c'=> 5, 'd'=> 5, 'e'=> 5, 'f'=> 4, 'g'=> 5, - 'h'=> 6, 'i'=> 4, 'j'=> 5, 'k'=> 6, 'l'=> 4, 'm'=> 9, 'n'=> 6, 'o'=> 5, - 'p'=> 6, 'q'=> 5, 'r'=> 6, 's'=> 5, 't'=> 4, 'u'=> 6, 'v'=> 6, 'w'=> 8, - 'x'=> 6, 'y'=> 6, 'z'=> 5, '{'=> 5, '|'=> 4, '}'=> 5, '~'=> 7 -); - -# my $tab_width = 4 * $width_table{'0'}; - - my $sum = 0; - my $c; - - foreach $c ( split(//,$str) ) { - $sum += $width_table{$c}; -# print "'$c' =>$width_table{$c}/$sum\n"; - } - - return $sum; -} - - -################ -# CalcTabs -################ - -sub CalcTabs { - my ($str,$tabn) = @_; - my $tab_width = 4 * StringWidth('0'); - my $tab_position = $tabn * $tab_width; - my $skip_dots = $tab_position - StringWidth($str); - my $more_tabs = 1; - - if ( $skip_dots > 0 ) { - $more_tabs += ($skip_dots - 1) / $tab_width; - } - -# print "["; print "$more_tabs:$skip_dots"; print "]"; - - return $more_tabs; -} - - -################ -# ExitToShell() -################ -# Macintosh specific routine - -sub ExitToShell { - -# if the runtime environment is a Macintosh. - &MacPerl'Quit(1) if $gMAC; - -# else then it is a Unix. - exit(0); -} - - -################ -# GetFileInfo() -################ -# Macintosh specific routine -# Returns a list ($creator,$type) - -sub GetFileInfo { - my ($filepath) = @_; - -# if the runtime environment is a Macintosh. - return &MacPerl'GetFileInfo($filepath) if $gMAC; - -# else then it is a Unix and if the file is a text file. - return ('????', 'TEXT') if -T $filepath; - -# otherwise returns nil. - return ('????', '????'); -} - -### end of script ###