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.
. 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.