NiceInputField by Jare - 16.7. - 19.7.2012 (version 1.00)
---------------------------------------------------------

NiceInputField (NIF) is a little library for CoolBasic Beta 10.43, which makes it possible to create comfortable single line text fields. Sorry, it does not offer multiline. That would be too complicated for me to program. With comfortable I mean that in NIF elements, you can highlight text, move the caret where ever you want and insert text there. Just as you expect how every text field should behave. Even cutting, copying and pasting is possible. NIF has an internal clipboard (text can be copypasted inside you application), which can be extended to system wide if you plug in cbAPI.

Contents:
 o Want to try?
 o Implement in your application
 o Controlling NIF elements (function reference)
 o System wide clipboard using cbAPI
 o Notice about how SCREEN command affects to NIF elements
 o Any updates?
 o About the author

Want to try it now?
-------------------

Just open and run Example.cb and try before getting your hands dirty on the code ;).

Implement in your application
-----------------------------

Including NIF into your project is simple. Put the following code line in to the beginning of your application's code:

Include "NiceInputField.cb"

Make sure NiceInputField.cb is located in the same directory with your project. Now compile your project just to check out if there are any name collisions with your project and NIF. Hopefully there isn't.

To have an input field being displayed in your application, you need to follow two more steps. Firstly, create a NIF element using this code:

nif_id = NIF_New("Hello world!")

NIF_New() is a function that creates our input field. You could have multiple fields in your application at the same time, but in this tutorial we only use one. The function takes only one parameter: what should be the default text content of the field. This parameter is optional and defaults to an empty string.

nif_id will contain an ID number that is required to access this field later. Without this we cannot get the field working at all.

The last step is to place the following code into your applications main loop:

NIF_InputKey = GetKey()
NIF_Draw(nif_id, x,y, width)

NIF_Draw() does most of the work. It does much more than just drawing :).

Parameters:
 - nif_id: The same ID we get from NIF_New().
 - x and y: Pixel coordinates of the top left corner of the field.
 - width: Total width of the field in pixels.
 
The function doesn't return anything.

NIF_InputKey is a global variable used to pass input of the keyboard to NIF. This input is provided us by CB's native GetKey() function. There are two reasons why NIF_Draw() does not use GetKey() directly:

1) GetKey() will lost it's value after one call. Compare to KeyHit(), which will reset its value on a DrawScreen or UpdateGame call, not after one call. When you are passing the value, you can also save it for yourself.

2) If you want to do some advanced stuff, you can manipulate the user's input. See Example.cb for more details.

Now we are done! Test you application and see how the typing goes. When you come back, we can get to learn how to control the NIF element from your application's code.


Controlling NIF elements
------------------------

There are some global variables in NiceInputField.cb that you should go and have a look at. They are global settings for all the NIF elements in your application. They are well commented so I do not repeat the information here. Here I will inroduce some functions you will find helpful.

NIF_Get()
---------

This function gives you information about a NIF element's properties.

Parameters:
 - nif_id
 - property (optional)

Property can be one of the following:
 - "content" (default): Returns all the text contained in the field.
 - "highlight": Returns a text that is highlighted in the field.
 - "part1": Returns all text BEFORE the caret
 - "part2": Returns all text AFTER the caret, including the character at the caret.
 - "caret": Returns position of the caret, starting from zero.
 - "locked": Returns 0 if the element is writable, 1 if the element is read only or 2 if the element is only visible but not listening to any commands from user.
 - "focus": Returns 1 if the field is active and can receive commands from the user. Returns 0 if it is not listening the user.


NIF_Set()
---------

This function can be used to assing values to some of a NIF element's properties. Note that the writable properties are partially different than readable properties in NIF_Get()!

Parameters:
 - nif_id
 - property (optional)
 - value

If you call this function with only two parameters, property will be "content" and value will have the value of the second parameter.

Property can be one of the following:
 - "content" (default): You can change the text in the field. Notice: Changing the content does not change the caret's position. The caret will be left where it was.
 - "caret": You can set the caret's position. The property can handle two different data types:
	- Integer [0 - n]: Indicates index of the letter the caret will be placed at. n = length of the field's content. Notice: this differs from CB's tradition to use character indexes starting from 1. In NIF, the indexes start from 0.
	- Float [0.00 - 1.00]: Indicates a percent. 0.00 will place the caret at the beginning and 1.00 will place the caret at the end of the text. Everything between is allowed. Remember to include dot character in order to tell that you are giving a float instead of an integer.
 - "locked": Possible values:
	- 0: User can write to the field and has a full control.
	- 1: User cannot write to the field, but can select text, move caret, scroll horizontally and copy text to clipboard.
	- 2: User cannot control the field at all. He/she is only allowed to see the element and the text in it. Scrolling is impossible so there is a possibility that the user cannot see all the content. In this state the field cannot have focus.
 - "focus": Set to 1 if you want to activate user controls on this field (all other NIF elements will loose focus). Set to 0 if you want to deactivate.
 - "highlight": Value can be one of the following:
	- "none": Will ensure that nothing is higlighted.
	- "all": Whole content will be highlighted. Caret will be moved to the end of the text.
	- Integer or float: Defines a single character that should be highlighted. Float is considered as a percent.
	- "a-b": A string containing two numbers separated by a hyphen. a = highlight starting position. b = highlight ending position. Numbers can be integers or floats (=percents).
 - "password": Value can be a single character or an empty string. If the value is a character, the field will be treated as a password field showing the desired character (usually *) instead of the content. Also note that in password mode, cutting and copying text is disabled. Pasting is still allowed. If the value is an empty string, password mode will go off.
 - "max_length": Defines a maximum count of characters the field can have.
	- If you set this to 0 or greater, the current content will be truncated to this length and future inputs will be disabled if it would break the limit.
	- If you set this to -1, no length limit will be used. This is the default value when creating a NIS element.

NIF_Insert()
------------

With this function you can insert text into a NIF element. Text will be inserted at the caret's position. Beware! If there is anything highlighted in the field, the highlighted text will get erased when this function is called. To prevent this, you can call NIF_Set(nif_id, "highlight", "none") before calling this function.

This function returns True on success and False on failure. The only reason for failing can be that you have defined a maximum length for the field and inserting the text you passed to this function would break that limit.

Parameters:
 - nif_id
 - text
 - move_caret (optional): Can be True (default) or False. If True, the caret will be moved to the end of the inserted text. Otherwise the caret will reside at the beginning of the inserted text.
 - highlight (optional): Can be True or False (default). If True, the inserted text gets highlighted.

NIF_Delete()
------------

This function takes a NIF ID as it's only parameter and removes the element from memory. Good way to clean up memory if you do not need a NIF element for a while. Beware! If you use this function, be certain that you do not use the passed NIF ID after the deletion! A terrible Memory Access Violation error message will haunt you and your application forever if you do so!


System wide clipboard using cbAPI
---------------------------------

Open NiceInputField.cb and find the function named NIF_Clipboard(). This function contains comments that tell you how to setup cbAPI to provide clipboard functions for NIF. The process is very simple.

Notice about how SCREEN command affects to NIF elements
-------------------------------------------------------

When NIF_Draw() is called the first time in your application, it automatically calls NIF_Initialize(), which creates an image that is used by NIF_Draw(). Normally you do not have to call NIF_Initialize yourself, but if you have a situation where you call SCREEN command AFTER drawing some NIF element, you have to call NIF_Initialize() in your application right after calling SCREEN. But if you only have one SCREEN call at the beginning of your application (with no NIF_Draw calls preceding that), you do not have to call NIF_Initialize(). All this is because SCREEN command deletes all images from the memory, including the one that NIF_Draw() needs.

Calling NIF_Initialize when not needed does not necessarily break anything, but it will consume more memory if called accidentally in a loop. It will also slow your application if you call it repeatedly.

To keep things simple: Try to build your application so that you do not need to call SCREEN after drawing a NIF element.


Any updates?
------------

My purpose was to make this library as finished as I could. I am not planning to add anymore features, so I really hope I will not need to make any updates. Though, if something very handy come into my or somebody else's mind, I may publish an update.

An update will come if:
 - Somebody suggests a well argued feature or improvement (and if I accept it and have time to program it)
 - Somebody finds a bug

All updates will be published in www.kpelit.fi/niceinputfield/ .

About the author
----------------

NiceInputField is made by me, Jarkko 'Jare' Linnanvirta in 2012. You can use the code how ever you want, but you are not allowed to say that it is made by somebody other than me. No credits are required to include in your application or anywhere, but if you like, you can mention me and the following contact information in your application, on a website or some other place:

jare@kpelit.fi
www.kpelit.fi/niceinputfield/
Nick Jare in CoolBasic forums (www.coolbasic.com/phpBB3/) and the same nick in www.kpelit.fi.

If you have anything to ask, please contact me. I'm also interested to know how many people use this library. You can freely email me about the application, project, etc. where you are using this library.