## IV. API Reference

[ Previous: G. Wiki-Link Functions | Next: I. Replaced-Item Functions ]

### H. Smiley Functions

void BBCode::AddSmiley ( string $`name` , string $`image` )
This function adds a new smiley. Smileys, or emoticons, are character symbols like `:-)` that get automatically converted to images like . To add a smiley, call AddSmiley() and provide the text of the smiley you wish to add or replace, and the name of an image that is to be displayed in its place. Any old smiley defined for that string will be removed by this function, so this can also replace smileys as well as adding new smileys.
Parameters:

- name: The name of a smiley you wish to add or replace, like "`:-)`" or "`:3`" or "`:frog:`". Nearly any name is allowed; however, beyond common sequences, you are encouraged to use names surrounded by `:`colons`:` so that they are not accidentally mistaken for non-smiley text.
- image: The name of an image located in the current smileys directory that you wish to have displayed in place of the text symbol.

Return Value: None.
(The user's manual, section III.D as well as appendix A, contains additional documentation on using this function, so that information will not be repeated here.)
void BBCode::RemoveSmiley ( string $`name` )
This function un-defines the given smiley --- in short, this causes NBBC to stop recognizing the given smiley and converting it to an image.
Parameters:

- name: The text form of a smiley to remove from the ruleset.

Return Value: None.
string BBCode::GetSmiley ( string $`name` )
This function returns the image for a given smiley, by name, the same array as was most recently given to AddSmiley() for that same smiley.
Parameters:

- name: The text form of the smiley whose image name you'd like to retrieve.

Return values: The image for the given smiley, if the smiley has been defined; if it has not, the return value is `false`.
void BBCode::ClearSmileys ( )
This function removes all smileys currently associated with this BBCode object, after which the BBCode object will have no smileys defined at all. This is useful if you want to replace the default smileys entirely with your own custom smileys.
Parameters: None.
Return Value: None.
array BBCode::GetDefaultSmiley ( string $`name` )
This function returns the default smiley image name for a given chunk of text, the same image name that would be used by a newly-constructed BBCode object. This provides you with an easy way to look up a smiley provided by the Standard Smileys.
Parameters:

- name: The text form of the smiley whose image name you'd like to retrieve.

Return values: The Standard Smiley's image name for the given text, if the text has been defined as a smiley; if it has not, the return value is `false`.
void BBCode::SetDefaultSmiley ( string $`name` )
This function changes the smiley for a given text string to the same image name that would be used by a newly-constructed BBCode object, the same image name that would be returned by GetDefaultSmiley().
Parameters:

- name: The text form of the smiley whose image name you'd like to revert to its default setting.

array BBCode::GetDefaultSmileys ( )
This function returns a key => value array that contains all of the default smileys --- all of the smileys in the set of Standard Smileys. Each key is a text string, and each value is the name of an image. This is exactly the same as calling GetDefaultSmiley() many times, once for each text string in the Standard Smileys, only much, much faster.
Parameters: None.
Return Value: An array containing all of the default smileys.
void BBCode::SetDefaultSmileys ( )
This function causes the BBCode object's entire current set of smileys to be replaced with the default smileys --- in other words, to be changed back to the smileys that it had just after it was newly-created --- in other words, to the ruleset for the Standard Smileys. All of the existing smiley definitions in this object will be deleted, and the new, default smiley definitions will be installed instead.
Parameters: None.
Return Value: None.
void BBCode::SetSmileyDir ( string $`fullpath` )
This function tells NBBC where smiley images are found, as a pathname relative to the root of the host's filesystem (an absolute pathname). You should usually use a full absolute pathname for this, like "`/home/larry/web/smileys`", and you should not include a trailing slash on the path, as one will be appended automatically. Using relative pathnames can work, but may produce problems on some web servers.
Parameters:

- `fullpath`: The filesystem path to your smiley directory.

string BBCode::GetSmileyDir ( )
This function returns the current smiley directory. See SetSmileyDir() for more details.
Return values: Returns the current smiley directory. If no smiley directory has been set, this returns simply "smileys".
string BBCode::GetDefaultSmileyDir ( )
This function returns the default local image directory.
Return values: Always returns "smileys".
void BBCode::SetSmileyURL ( string $`url` )
This function tells the browser where smileys are found, as an absolute URL. You should usually use a full absolute URL for this, like "`http://larry.example.com/smileys`", and you should not include a trailing slash on the path, as one will be appended automatically. Using relative (short) URLs can work, but may produce problems with some web browsers if not used carefully.
Parameters:

- `url`: The full URL to your smiley directory.

string BBCode::GetSmileyURL ( )
This function returns the current smiley URL. See SetSmileyURL() for more details.
Return values: Returns the current smiley URL. If no smiley URL has been set, this returns simply "smileys".
string BBCode::GetDefaultSmileyURL ( )
This function returns the default smiley URL.
Return values: Always returns "smileys".
void BBCode::SetEnableSmileys ( bool $`enable` )
This function determines whether smileys like `:-)` are converted to images or whether they are ignored and treated as plain text.
Parameters:

- `enable`: If set to `true`, all defined smileys are converted to their matching images; this is the default behavior. If set to `false`, all smileys are treated the same as any other text and passed to the output unchanged.

bool BBCode::GetEnableSmileys ( )
This function returns the current enable-smileys state. See SetEnableSmileys() for more details.
Return values: Returns `true` or `false`, depending on whether smileys are being converted to images.
void BBCode::SetMaxSmileys ( int $`count` )
This function sets the maximum number of smileys that may be used in a single parsed string.
Parameters:

- `count`: The maximum number of smileys that may be used in a parsed string. Set to `-1` to make unlimited, which is the default.

int BBCode::GetMaxSmileys ( )
This function returns the current maximum number of smileys that may be parsed in a single parse.
Return values: Returns the maximum number of smilies per parsed string. `-1` indicates an unlimited number of smileys.

[ Previous: G. Wiki-Link Functions | Next: I. Replaced-Item Functions ]

Copyright © 2010, the Phantom Inker. All rights reserved.