A

Plug-in API

This chapter provides information on the BeIDE plug-in API (application programming interface) that allows you to extend the capabilities of the BeIDE.

## Plug-in API Overview

The BeIDE can utilize any command-line tool during the normal build process. This gives developers great flexibility in controlling builds. The intention is to separate tool-specific code from the project manager and build capabilities of BeIDE.

The topics covered in this chapter include:

- `Changes to This Version`
- `Parts of a Plug-in`
- `What Happens and When?`
- `Function Reference`

In order for a tool to be supported by BeIDE a plug-in that contains code for one or more `MPlugInPrefsView` objects and an `MPlugInBuilder` object must be available. The `MPlugInPrefsView` will be shown in the Settings window and settings created by this view will be stored in the project. At build time the `MPlugInBuilder` object will be called and asked to generate an `argv` list for each source file targeted to the tool supported by that builder object. The targets preferences panel provides a mechanism for the project manager to associate source files with specific tools and to specify the stage of make during which a particular source file is executed.

The BeIDE supports command-line tools that are not aware of the IDE as well as tools that are IDE-aware. IDE-aware tools have access to a port-based interface to the IDE that allows greater access to the information stored in a project than is possible through an argv interface. Non-IDE-aware tools are simply launched as if from the command line and won't require any rewrite in order to function as part of the build process.

See the accompanying project for the shell tool plug-in for a working example of how to write a plug-in.

## Changes to This Version

The primary changes to this version include:

- The parameter lists to the `BuildPrecompileArgv`(), `BuildCompileArgv`() and `BuildPostLinkArgv`() methods have changed.
- Numerous other new methods in the API are now available. Refer to the `Function Reference` for a comprehensive description of the API.

## Parts of a Plug-in

Plug-ins are straightforward add-ons. They must export two functions with the prototypes as shown in `Listing A.1`.

Listing A.1 Plugin prototypes

    #pragma export on

    extern "C"

    {

    	status_t MakePlugInView(long inIndex, BRect inRect,

    											MPlugInPrefsView*& outView);

    	status_t MakePlugInBuilder(long inIndex,

    											MPlugInBuilder*& outBuilder);

    }

    #pragma export reset

These functions are called repeatedly until they return a value other than `B_NO_ERROR`. `inIndex` will start at zero and be incremented for each call. `inRect` is the frame rect for the preferences view in coordinates of the Settings window. `outView` and `outBuilder` are references to object pointers for the view and builder objects that are returned by the add-on.

When called, the `MakePlugInView` and `MakePlugInBuilder` functions should generate the view and builder objects that match `inIndex`, should place those object pointers in the respective `outView` or `outBuilder` parameters, and should return `B_NO_ERROR`. Once `inIndex` is greater than the number of views or builders that the add-on generates it should return `B_ERROR`.

A given add-on can generate multiple views and builders. A view needn't have a matching builder object. However, each builder object must be associated with at least one view. In the case where a given tool requires multiple prefs views only a single builder object should be generated for the tool.

In the simplest and most common case the add-on will generate a single view and matching builder. The view that is returned must be a subclass of `MPlugInPrefsView` and the builder must be a subclass of `MPlugInBuilder`. Header files describing those classes accompany this document. Both classes are pure virtual with a number of functions that must be overridden in any subclasses. Some of the functions won't apply for all subclasses but they must all be overridden. See the function descriptions below and the shell tool plug-in project for more information on what each function does.

## What Happens and When?

Plug-ins are loaded when BeIDE launches. The `MakePlugInBuilder` function will be called shortly after launch and before any windows appear. The `MakePlugInView` function is called a bit later but before any project windows appear. The Settings window is persistent, being created at app launch and existing until app quit. `MPlugInPrefsViews` will be destructed when the Settings window is destructed at app quit time. `MPlugInBuilders` will be destructed shortly before the views are destructed, also at app quit time. Ownership of the views and builders passes to the IDE and they shouldn't be destructed by any plug-in code.

`MPlugInPrefsViews` will be shown and hidden under user control.

`MPlugInBuilders` will be called to validate settings data at various times and will be called to generate `argv` lists for each source file.

The build process consists of four stages, precompile, compile, link, and postlink, which execute in that order. Files for each stage are executed from top to bottom in the project window and all files for one stage will execute before the next stage is begun. The precompile and postlink stages execute only a single file at a time. The compile stage will execute up to four files concurrently based on the setting in the `Project' preferences panel. The link stage is a bit different with only a single linker being launched.

Source files are targeted to a particular stage by their file type and file extension, as set in the Targets preferences panel. Source files are also associated with an `MPlugInBuilder` object based on the toolname specified by that object and the toolname specified in the target record in the Targets preferences panel. The relationship is Source File->Target record->MPluginBuilder(s).

The precompile and compile stages are rather similar. The link stage is special. One linker exists for any project, and this linker is chosen in the Target settings panel (go to the menu `Window`, choose the menu item `Settings`, choose the panel Target). At link stage, the linker builder is `BuildLinkArgV` method is called, giving the linker builder the opportunity to generate an `argv` list for the link stage.

After a successful link the postlink stage is begun. First all resources in source files are copied to the executable. Files containing resources are indicated by the `hasResources` flag set in the Targets preferences panel. The make stage and toolname are ignored for the resource copy step. Next the access permissions are set for the executable with a call to `chmod()` and the file type and creator signature are set. Finally, those source files targeted to the postlink stage are executed.

## Function Reference

Here are the functions used to support plug-ins:

#### `MPlugInPrefsView`

- `MPlugInPrefsView`
- `Title`
- `Targets`
- `GetData`
- `SetData`
- `GetPointers`
- `DoSave`
- `DoRevert`
- `DoFactorySettings`
- `UpdateValues`
- `ValueChanged`
- `FilterKeyDown`
- `ProjectRequiresUpdate`
- `SetDirty`
- `IsDirty`

#### `MPlugInBuilder`

- `~MPlugInBuilder`
- `GetToolName`
- `LinkerName`
- `MakeStages`
- `Actions`
- `Flags`
- `MessageDataType`
- `ValidateSettings`
- `BuildPrecompileArgv`
- `BuildCompileArgv`
- `BuildPostLinkArgv`
- `FileIsDirty`
- `ParseMessageText`
- `CodeDataSize`
- `GenerateDependencies`
- `GetTargetFilePaths`
- `ProjectChanged`

#### `MPlugInLinker`

- `TargetName`
- `BuildLinkArgv`
- `GetExecutableRef`
- `GetBuiltAppPath`
- `IsLaunchable`
- `Launch`

#### `MProject`

- `GetProjectRef`
- `GetExecutableRef`
- `GetBuiltAppPath`
- `FileCount`
- `GetNthFile`
- `LinkerName`
- `GetPrefs`
- `SetPrefs`
- `RunsWithDebugger`
- `Launch`

#### `MTextAddOn`

- `Text`
- `TextLength`
- `GetSelection`
- `Select`
- `Delete`
- `Insert`
- `Window`
- `GetRef`
- `IsEditable`

### MPlugInPrefsView

Here are the descriptions of the methods defined in the `MPlugInPrefsView.h` header file.

#### MPlugInPrefsView

`MPlugInPrefsView::MPlugInPrefsView`

The constructor does nothing and is there to allow subclasses to call the `BView` constructor.

#### Title

``virtual const char * Title();``

Returns the title of the prefs view. This title is used for the text in the scrolling list of prefs panels in the Settings window. The title may also indicate the section of the scrolling list in which the prefs panel should be placed. This is done with a title like:

``"Project/Target"``

where `Project' is the section and `Target' is the name of the prefs panel. If no section is specified the prefs panel will go into a section at the end titled `Other.' There is no need to specify `Other' in your panel titles since they'll end up there anyway. You may not add additional sections to the scrolling list.

#### Targets

``virtual TargetT Targets();``

Each prefs panel can be targeted to one or more parts of the project manager. These targets are shown in the Apply To popup in the Settings window. In almost all cases the targets for plug-in prefs panels will be new projects and the current project. The Targets function will almost always look like the code in `Listing A.2`.

Listing A.2 Targets example

    TargetT

    MSamplePlugInView::Targets()

    {

    	return (kMWDefaults | kCurrentProject);

    }

Note that `target' in this sense is not directly related to the Targets prefs panel, but rather is related to the choices in the ApplyTo popup.

#### GetData

``virtual void GetData(BMessage inOutMessage);``

Preferences data is passed to and from preferences views and builders in `BMessages`. `BMessages` are suited for this because they are general container objects. It is simple to add arbitrary data to a `BMessage` and later retrieve that data by name and type.

Each builder object has a type associated with it. At build time all data of that type will be passed to the builder, which will be able to distinguish between different preferences data by the unique names. The preferences view objects that match that builder object can edit this sort of data (usually one struct per preferences view).

`GetData` is called with an empty `BMessage`. The preferences view should add the appropriate data to that message as shown in `Listing A.3`.

Listing A.3 GetData example

    const char* kSampleMessageName = "SampleData";

    const ulong kSampleMessageType = 'SamD';

    void

    MSamplePlugInView::GetData(BMessage& inOutMessage)

    {

    	inOutMessage.AddData( kSampleMessageName, kSampleMessageType,

    											&fNewSettings, sizeof( fNewSettings ));

    }

`GetData` will be called at several times: when the Save button is clicked, and when the target of the prefs view changes, which happens when the ApplyTo popup is changed. The Settings window uses the name and type of the data in the BMessage to obtain the current settings for this view from the applyto target.

#### SetData

``virtual void SetData(BMessage inOutMessage);``

`SetData` will be called when the current settings of a target need to be displayed in the view. The view should look in the BMessage for data of the type and name that the preference view edits and should make a copy of the data and update the view reflecting the new prefs data as shown in `Listing A.4`.

Listing A.4 SetData example

    void

    MSamplePlugInView::SetData( BMessage& inMessage )

    {

    	if (inMessage.HasData(kSampleMessageName, kSampleMessageType))

    	{

    		long			length;

    		SamplePrefs*		prefs = (SamplePrefs*) inMessage.FindData

    											  ( kSampleMessageName, kSampleMessageType,

    											  &length);

    		fNewSettings = *prefs;

    		fOldSettings = fNewSettings;

    		UpdateValues();

    	}

    }

#### GetPointers

``virtual void GetPointers( void *outOld, void *outNew, long outLength);``

In most cases the prefs data generated by plug-in views and utilized by builders will be represented by a simple struct. In those cases the Settings window can handle a number of functions for the preferences view including saving, reverting, and determining if the prefs data have changed. If the prefs data can be represented as a simple struct `GetPointers` should set the values of the `outOld`, `outNew`, and `outLength` parameters to point to the `oldvalues` struct, `newvalues` struct, and the length of these structs.

The strategy to be used for maintaining these structs is to have two copies of the struct as member variables of the preferences view.

Listing A.5 GetPointers example

    struct SampleData {

    	long version;

    	long fieldOne;

    	bool fieldTwo;

    };

    SampleData		 fNewSettings;

    SampleData		 fOldSettings;

The `fOldSettings` struct holds the initial settings obtained in the `SetData` call. The `fNewSettings` struct holds values that result when the user manipulates subviews in the preferences view. The fNewSettings struct should be updated after every change that the user makes. The Settings window can then do a Revert simply by copying the `fOldSettings` struct to the `fNewSettings` struct and calling UpdateValues. Other actions can be performed in a similar fashion.

The Settings window uses `memcmp` to compare the old and new settings structs to determine whether the revert and save buttons should be enabled. It is important that all padding bytes and other unused portions of the two structs are identical. For instance if there are strings in the struct the entire string array should be set to zero with `memset` before copying the string into the struct.

#### DoSave

`virtual void DoSave();`

This function will be called only if `GetPointers` doesn't return valid values. It will be called after the Save button is clicked. The preferences view should copy its data structures that hold the new prefs data to the data structures that hold the old prefs data.

#### DoRevert

`virtual void DoRevert();`

This function will be called only if `GetPointers` doesn't return valid values. It will be called after the Revert button is clicked. The preferences view should copy its data structures that hold the old prefs data to the data structures that hold the new prefs data.

#### DoFactorySettings

`virtual void DoFactorySettings();`

This function will be called when the factory settings button is clicked. The preferences view should replace the new settings values with appropriate defaults. The old settings values shouldn't be changed.

#### UpdateValues

`virtual void UpdateValues();`

At various times the Settings window may modify the new settings struct. If it does it will call this function. The preferences view should read all the values from the new settings struct and set the values of all the subviews accordingly.

#### ValueChanged

`virtual void ValueChanged();`

Use this function to post a message to the settings window letting it know that there has been a change in the structs containing the data for this view. The settings window will adjust the buttons based on the values in those structs.

    Window()->PostMessage(msgPluginViewModified);

#### FilterKeyDown

`virtual bool FilterKeyDown(ulong aKey)`

This function is no longer used.

#### ProjectRequiresUpdate

`virtual bool ProjectRequiresUpdate( UpdateType inType );`

If the applyto target of the prefsview is the current project, certain changes will require all of the files in the project to be recompiled, or will require the project to be relinked. Return `true` if changes in the prefsview will require the specified type of changes in the project.

#### SetDirty

This method sets the dirty flag. This flag indicates whether the preferences have changed.

#### IsDirty

This method allows you to query the dirty flag. This flag indicates whether the preferences have changed.

### MPlugInBuilder

This section describes the methods in the `MPlugInBuilder.h` header file.

#### ~MPlugInBuilder

`~MPlugInBuilder`

The destructor doesn't do anything but is present so that any derived class destructors will be virtual.

#### GetToolName

`virtual long GetToolName( char* outName, int32 inBufferLength, MakeStageT inStage, MakeActionT inAction);`

This function returns the name of the tool associated with this builder. This toolname is used to associate a tool with a given source file based on the information in the Targets prefs panel. The tool may reside in `/boot/develop/tools` or in`/boot/bin`, in which case the toolname can be simply the filename of the tool (e.g, "`mwcc`", "`sh`"). Alternatively the toolname may be a full path to the tool, in which case it may reside anywhere in the file system. In either case, the toolname should be copied to the buffer specified by `outName` and `inBufferLength`.

Under certain circumstances, multiple tools can be associated with a single builder depending on the make stage and make action.

#### LinkerName

`virtual const char * LinkerName();`

Returns the linker name in a character string.

#### MakeStages

`virtual MakeStageT MakeStages();`

Returns a mask that indicates the stages of make at which this tool can act as shown in `Listing A.6`. See `PlugInPreferences.h` for valid values of this mask.

Listing A.6 MakeStages example

    MakeStageT

    MSampleBuilder::MakeStages()

    {

    	return (kPrecompileStage | kCompileStage);

    }

#### Actions

`virtual MakeActionT Actions();`

Return a mask that indicates the actions this tool can perform at make time as shown in `Listing A.7`. See `PlugInPreferences.h` for valid values of this mask.

Listing A.7 Actions example

    MakeActionT

    MSampleBuilder::Actions()

    {

    	return ( kPrecompile | kCompile | kPostLinkExecute );

    }

#### Flags

`virtual PlugInFlagsT Flags();`

Return certain flags regarding this builder. Currently the only flags defined indicate whether the tool is IDE-aware or not. Most tools will not be IDE-aware.

Listing A.8 Flags example

    PlugInFlagsT

    MSampleBuilder::Flags()

    {

    	return kNotIDEAware;

    }

#### MessageDataType

`virtual ulong MessageDataType();`

The message data type is the type of data added to the `BMessage` in the `MPlugInPrefsView::``SetData` function. At build time the build system will copy all data of this type from the project and pass it to the `BuildArgv` functions so they can use it to generate their argv lists.

### NOTE:

Remember that for endian compatibility, the same bit pattern must be returned, regardless of the host endianess.

#### ValidateSettings

`virtual bool ValidateSettings (BMessage& inOutMessage);`

This function is called to give the builder the opportunity to verify that the prefs data in the message is valid. The builder should inspect the message for all data that the builder will require when generating an `argv` list. If any data is missing it should be added to the message. If any data is in an old format or is otherwise invalid it should be replaced in the message. Return true if something in the message was changed.

This function will be called shortly after app launch to validate the new project settings and shortly after any project is opened. It will help this validation step if the preferences data has a version field in it. If possible when updating to a new prefs version format the existing values should be copied to the new struct.

Listing A.9 ValidateSettings example

    bool

    MSampleBuilder::ValidateSettings( BMessage inOutMessage )

    {

    	SampleData	defaultPrefs = { kCurrentVersion, 1L, true };

    	bool		changed = false;

    	if (inOutMessage.HasData(kSampleMessageName,

    			kSampleMessageType))

    	{

    		long			len;

    		SampleData*		prefsPtr = (SampleData*)

    				inOutMessage.FindData( kSampleMessageName,

    														   kSampleMessageType, &len);

    		if (prefsPtr->version != kCurrentVersion ||

    				len != sizeof(SampleData))

    		{

    			inOutMessage.ReplaceData( kSampleMessageName,

    															 kSampleMessageType,

    															 &defaultPrefs,

    															 sizeof(defaultPrefs));

    			changed = true;

    		}

    	}

    	else

    	{

    		inOutMessage.AddData(kSampleMessageName, kSampleMessageType,

    				&defaultPrefs, sizeof(defaultPrefs));

    		changed = true;

    	}

    	return changed;

    }

#### BuildPrecompileArgv

`virtual long BuildPrecompileArgv( BList& inArgv,`
`MFileRec inFileRec );`

There are four stages of make and four functions for building `argv` lists. These functions have similar but not identical parameter lists. This function will be called as part of a Make or Bring Up To Date. It should return `B_NO_ERROR` if a valid argv list was generated.

### NOTE:

The Link step `BuildArgv` function is not public in this release of the BeIDE plug-in API.

`inArgv` is a `BList` object. It is empty on entry and holds the argv arguments on exit. These arguments must be pointers to strings allocated with `malloc`, or more commonly with `strdup`. The arguments will be passed to the tool in the order that they appear in the `BList`. Do not add a `NULL` entry at the end.

inFileRec is the file record that references the path of the file to be executed.

A simple `BuildPrecompileArgv()` function might look like the code in `Listing A.10`.

Listing A.10 BuildPrecompileArgv example

    long MShellBuilder::BuildPrecompileArgv(

    	BList& 		inArgv,

    	MFileRec& 	inFileRec)

    {

    	return BuildArgv(inArgv, inFileRec.path);

    }

#### BuildCompileArgv

`virtual long BuildCompileArgv( BList& inArgv, MakeActionT inAction, MFileRec& inFileRec );`

The parameters for `BuildCompileArgv()` are similar to those for ```BuildPrecompileArgv```() except that there is an additional `inAction` parameter. The only valid action at the precompile stage is `kPrecompile`. However, at the compile stage a number of actions are valid (`kPrecompile`, `kCompile`, `kPreprocess`, `kCheckSyntax`, and `kDisassemble`). This function will be called when any of the above actions are initiated from menu items in the Project Window or source windows. This function will also be called for source files during the compile stage of a Make or Bring Up to Date.

#### BuildPostLinkArgv

`virtual long BuildPostLinkArgv( BList & inArgv, MFileRec& inFileRec );`

This function will be called for source files that are executed in the postlink stage. The executable will already exist and its inFileRec is passed as a parameter.

#### FileIsDirty

`virtual bool FileIsDirty( MFileRec& inFileRec, MakeStageT inStage, MakeActionT inAction, time_t inModDate );`

During a Make or Bring up to Date the build system only executes those files that have been modified since the last successful compile or have been expressly `touched,' or those which have dependent files that have been modified. For each source file the build system will check each of those things. If it determines that the file hasn't been modified it will call this function in the builder to allow the builder to additionally determine if the file needs to be executed. Return `true` if the file needs to be executed. For instance if the tool generates a second file when it executes the source file this function should check for the presence of this second file and should compare its modification date with that of the source file.

inFileRec is the `file record` of the source file. `inAction` is the action. `inModDate` is the modification date of the source file as returned from `BEntry:GetModificationTime()`;

#### ParseMessageText

`virtual long ParseMessageText( const char* inText, BList& outList);`

Non-IDE-aware tools commonly send messages to `stderr` or `stdout`. When launching non-IDE-aware tools the build system captures these messages. In order for them to appear in the Message window in some meaningful way this function will be called. Its job is to take the text specified in inText, break it into `ErrorMessage` structs and add these structs to `outList`. The `ErrorMessage` struct is defined in `ErrorMessage.h`. This function will not be called for IDE-aware tools.

The `ErrorMessage` struct holds a large number of variables to precisely locate the error so that double-clicking the error in the Message window will open the file and select the error, even if some text in the source file has changed. In most cases though this information will not be available from command-line tools and may not be relevant. In those cases simply set the `textonly` field to true and copy the text to the `errorMessage` field of the struct.

`inText` is the text that is captured from `stderr` and `stdout`. It is additionally terminated with a null character. Allocate `ErrorMessage` structs with operator `new`. For example:

Listing A.11 ParseMessageText example

    ErrorMessage*	msg = new ErrorMessage;

    msg->textonly = true;		// ignore most of the fields in the struct

    msg->isWarning = false;		// it's an error not a warning

    msg->filename[0] = 0;		// no filename

    memcpy(msg->errorMessage, &text[beginOffset], textLen);

    outList.AddItem(msg);

#### CodeDataSize

`virtual void CodeDataSize( const char* inFilePath, int32& outCodeSize, int32& outDataSize);`

This function will be called for non-IDE-aware tools after the successful execution of a source file. The code size and data size values returned will be displayed in the project window. If code size and data size aren't relevant for a given source file return a negative value.

#### GenerateDependencies

`virtual long GenerateDependencies( const char* inFilePath, BList& outList);`

This function will be called for non-IDE-aware tools after the successful execution of a source file. This gives the builder the opportunity to specify files that this source file depends on. For future builds this source file will be executed if the modification date for one or more of the dependent files is more recent than the last successful compilation time for the source file. `inFilePath` is a full path to the source file. `outList` is a reference to a `BList` that should have `entry_ref`*s added to it. return `B_NO_ERROR` if no errors occurred.

Listing A.12 GenerateDependencies example

    entry_ref* ref = new entry_ref;

    FillInDependentFileRecordRef(ref); // fill in ref

    outList.AddItem(ref);

    return B_NO_ERROR;

#### GetTargetFilePaths

`virtual void GetTargetFilePaths(`
`MFileRec& inFileRec,`
`BList& inOutTargetFileList) = 0;`

Fill the list with the full paths to the target file(s) generated when the source file is compiled. This function is called when the linker needs to know which files to link, and when the user chooses the remove objects menu item.

The path must be allocated with malloc. If no target files are generated then simply return.

#### ProjectChanged

`virtual void ProjectChanged(`
`ChangeT inChange, MProject* inProject) = 0;`

Thie method is called when a project has changed. The specific reason that the project changed is specified by the `ChangeT` enum in `MPlugInBuilder.h`.

The `MProject` callback object allows the builder object to find out various kinds of information about the current project. The `MProject` object passed in can be cached by the builder object and used at a later time. It will be valid between calls that specify `kProjectOpened` and the matching `kProjectClosed`.

### MPlugInLinker

This section describes the methods in the `MPlugInLinker.h` header file. This object inherits from `MPlugInBuilder`.

#### TargetName

``virtual const char * TargetName();``

This method returns the name that is displayed in the Target pop-up menu in the Target settings panel, when this linker has been selected.

#### BuildLinkArgv

``virtual long BuildLinkArgv( BList& inArgv );``

This method adds the `argv` for the link stage to the list.

#### GetExecutableRef

`virtual status_t GetExecutableRef(entry_ref& outSYMFileRef);`

This function is called by the BeIDE to determine the `entry_ref` of the executable.

#### GetBuiltAppPath

`virtual status_t GetBuiltAppPath( char * outPath, int32 inBufferLength);`

Given a pointer to a buffer and a buffer length, this method fills the buffer with the path that the code will be output to. This method is called by the BeIDE.

#### IsLaunchable

`virtual bool IsLaunchable();`

This method is called by the BeIDE to determine whether the Run or Debug menu items should be enabled.

For example, static libraries are not launchable.

#### Launch

`virtual status_t Launch( bool inRunWithDebugger);`

This method is called by the BeIDE when the user chooses the Run or Debug menu items. In most cases, calling `MProject::Launch` will work, but any special processing can go here.

### MProject

This object allows you to query and manipulate the properties of the project.

#### GetProjectRef

`virtual status_t GetProjectRef( entry_ref& outEntryRef);`

This method allows you to retrieve a reference to the current project.

#### GetExecutableRef

`virtual status_t GetExecutableRef( entry_ref& outEntryRef);`

This method is the same as `GetExecutableRef` in `MPlugInLinker`.

#### GetBuiltAppPath

`virtual void GetBuiltAppPath*(char * outPath, int32 inBufferLength);`

This method is the same as `GetBuiltAppPath` in `MPlugInLinker`.

#### FileCount

`virtual int32 FileCount();`

This method returns the number of files in the project.

#### GetNthFile

`virtual bool GetNthFile( MFileRec& outRec,
BList& outTargetList, int32 inIndex);`
`virtual bool GetNthFile( MFileRec& outRec, int32 inIndex);`

This method allows you to retrieve a file record for a given file.

#### LinkerName

`virtual const char * LinkerName();`

This method returns the name of the linker for this project.

#### GetPrefs

`virtual void GetPrefs( uint32 inPrefsType,
BMessage& inoutMessage);`

This method allows you to get a message that contains the preferences associated with a particular Prefs type. Refer to `Listing A.13` for a short example code snippet.

Listing A.13 GetPrefs() example listing

    fProject->GetPrefs(kShellMessageType, msg);

    if (B_NO_ERROR == msg.FindData(kShellMessageName,

     kShellMessageType, &prefs, &length)) {

    	memcpy(&fShellPrefs, prefs, length);	// Make a copy of the prefs

    }

#### SetPrefs

`virtual void SetPrefs( BMessage& inMessage, uint32 inUpdateType);`

This method allows you to manipulate the preferences.

#### RunsWithDebugger

`virtual bool RunsWithDebugger();`

This method allows you to detect whether a project will run with the debugger.

#### Launch

`virtual status_t Launch( entry_ref& inRef );`

This method allows you to launch the executable. It is usually called from `MPluginLinker::Launch`.

### MTextAddOn

This is a proxy class that forwards function calls to the actual BView subclass that is present in source windows in the BeIDE. Use of a proxy class allows changes in the implementation of BeIDE source windows without requiring changes in the Editor AddOns. MTextAddOn doesn't inherit from BView. AddOns written prior to release of this API will not be compatible with it without some changes.

Editor AddOns are installed in the develop/plugins/Editor_add_ons directory. They are loaded when the BeIDE launches and are available from the AddOns menu in source windows.

The add-on must export a function with the following prototype:

`extern "C" long perform_edit(MTextAddOn* inAddOn);`

When chosen from the Add-ons menu this function is called with a pointer to an MTextAddOn object that will forward editing functions to the view. Don't cache the MTextAddOn* as it may not exist longer than the perform_edit function call.

See the accompanying project for the Commenter editor AddOn on the CodeWarrior for BeOS CD.

### TIP:

The constructor and destructor are not accessible from the add-on. Don't attempt to create one of these objects and don't attempt to delete the object that is passed in to the perform_edit function.

#### Text

`virtual const char* Text();`

Returns a pointer to the text in the view. Don't modify this text in any way. The pointer is only valid until the next non-const member function is called.

Use the `Insert` and `Delete` functions to modify the text.

#### TextLength

`virtual int32 TextLength() const;`

Returns the length of the text in the view.

#### GetSelection

`virtual void GetSelection( int32 *start, int32 *end) const;`

Returns the start and end of the selection by reference.

#### Select

`virtual void Select( int32 newStart, int32 newEnd);`

Sets the selection.

#### Delete

`virtual void Delete();`

Removes the text in the current selection.

#### Insert

`virtual void Insert( const char* inText);`
`virtual void Insert( const char* text, int32 length);`

Inserts text at the current selection.

#### Window

`virtual BWindow* Window();`

Returns a pointer to the BWindow object that the view resides in. You might use this to get the name of the window.

#### GetRef

`virtual status_t GetRef( entry_ref& outRef);`

Returns the entry_ref of the file that is displayed by this window. Will return B_OK if there were no errors.

#### IsEditable

`virtual bool IsEditable();`

Returns true if the file can be edited. returns false if the file is on a read-only device or the file is marked as non-writable by the file permissions.

Visit the Metrowerks website at: http://www.metrowerks.com
For assistance contact Metrowerks Technical Support at: support@metrowerks.com
Copyright © 1998, Metrowerks Corp. All rights reserved.
Last updated: February 15, 1998
* Chris Magnuson * John Roseborough