|
Code:
#############################################
# #
# Kovu's KX-Files Database v1.0.1 #
# Functions / Class Reference #
# #
# (c) Markus Fumagalli "Kovu", terrasco.net #
# October 16 2009 #
# #
#############################################
1) SUPPORTED FILE TYPES
*.xf3 (X-Files 3 DB)
*.xfi (X-Files DB [v1 + v2])
*.csv (Comma Separated Values)
*.dbf (dBase DB [only when PHP's dBase module is loaded])
2) CONSTANTS & PRESET VARS
X-Files presets:
$XFI_view_bool (true / false)
KX-Files constants:
XFD (delimiter)
XFSORT_UP (table sort up)
XFSORT_DOWN (table sort down)
dBase data types:
BOOLEAN_FIELD (L)
CHARACTER_FIELD (C)
DATE_FIELD (D)
NUMBER_FIELD (N)
*.dbf file-handling modes:
READ_ONLY (0)
WRITE_ONLY (1)
READ_WRITE (2)
3) X-FILES DATA TYPES
- string (default, occurs if the used type is not known or none is set)
- integer (number)
- bool (boolean 1 [true] or 0 [false])
- booltext (textual representation of boolean "true" or "false")
- date (MM/DD/YYYY)
- time (HH:MM:SS)
- timestamp (unix time stamp)
- dot1 (decimal number, 1 position)
- dot2 (decimal number, 2 positions)
- dot3 (decimal number, 3 positions)
- dot6 (decimal number, 6 positions)
4) GLOBAL FUNCTIONS
============================================
¦ array_insert($array, $insert, $position) ¦
============================================
Inserts an array ($insert) at the specified position of the main array ($array).
Returns true on success and false on fail.
==================================
¦ use_xfi_type($usetype, $value) ¦
==================================
Converts and returns $value in one of the X-Files formats. Returns false on fail,
however, keep in mind that type "bool" may return a valid false. If the preset
variable $XFI_view_bool is true, type "bool" will be returned as "booltext".
5) FILE HANDLING / TABLE CREATION
==============================
¦ $xfi = new KXFiles($path); ¦
==============================
Opens existing file at $path.
=========================================================================
¦ $xfi = new KXFiles($path, $cellnames, $celltypes, $title, $password); ¦
=========================================================================
Creates a new table with 1 empty row. $path doesn't need to be set, as it can be
redefined later. $cellnames holds the cell names, $celltypes the cell types. The
values are separated by comma, example:
$cellnames = "Cell 1,Cell 2,Cell 3";
$celltypes = "string,integer,string";
$title and $password are optional. Note that while you can set a $password for
X-Files DBs, the password only avoids manipulations through the X-Files library.
The databases are open text files which can be read by anyone who has file-reading
permissions on these files.
!!!!!!!!!!!!!!!!!!!!
!! Important Note !!
!!!!!!!!!!!!!!!!!!!!
The KX-Files constructor knows a 6th parameter: $csvdelimiter. It defaults to ","
for splitting CSV values. If you have CSV files using another delimiter, you can
alter that setting for KX-Files there.
====================================
¦ $xfi -> write($path, $password); ¦
====================================
Writes all data to the file. $path is optional if it has been defined before
(when loading or creating the file, or by manually setting the path later).
$password is optional when 'you've performed a object-wide login before' or no
'password has been set for the table'. Returns true on success or false on fail.
========================
¦ $xfi -> CheckTable() ¦
========================
Checks if the database table has been opened properly. Returns true if everything
is ok, and false if not. KX-Files automatically calls that method at every attempt
of accessing or manipulating data from the table. You should call CheckTable()
manually after creating or opening tables, in order to assure your code can work
with the table.
6) DB MANIPULATION
============================
¦ $xfi -> LogIn($password) ¦
============================
Performs an object-wide login to the X-Files table.
====================
¦ $xfi -> LogOut() ¦
====================
Performs an object-wide logout to the X-Files table.
==============================
¦ $xfi -> GetMode($password) ¦
==============================
Returns file-mode ("X-Files 3", "X-Files 1", "CSV file", "dBase"). $password
is optional when 'you've performed an object-wide login before' or 'no password
has been set for the table'. Returns false on fail.
==============================
¦ $xfi -> GetCSVD($password) ¦
==============================
Returns current CSV delimiter. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
false on fail.
==========================================
¦ $xfi -> SetCSVD($delimiter, $password) ¦
==========================================
Sets a CSV delimiter. $password is optional when 'you've performed an object-wide
login before' or 'no password has been set for the table'. Returns true on success
or false on fail.
=============================
¦ $xfi -> GetRow($password) ¦
=============================
Returns the current row. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
false on fail.
==============================
¦ $xfi -> GetCell($password) ¦
==============================
Returns the current cell. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
false on fail.
==============================
¦ $xfi -> GetType($password) ¦
==============================
Returns the data type of the current cell. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns false on fail.
===================================
¦ $xfi -> GetTypeTable($password) ¦
===================================
Returns the type-table (array) of the database. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'. Returns false on fail.
===================================
¦ $xfi -> GetNameTable($password) ¦
===================================
Returns the cell-name-table (array) of the database. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'. Returns false on fail.
===================================
¦ $xfi -> GotoFirstRow($password) ¦
===================================
Selects the first row of the database. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns true on success or false on fail.
====================================
¦ $xfi -> GotoFirstCell($password) ¦
====================================
Selects the first cell. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
true on success or false on fail.
==================================
¦ $xfi -> GotoLastRow($password) ¦
==================================
Selects the last row of the database. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns true on success or false on fail.
===================================
¦ $xfi -> GotoLastCell($password) ¦
===================================
Selects the last cell. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
true on success or false on fail.
==================================
¦ $xfi -> GotoNextRow($password) ¦
==================================
Selects the next row in the database. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns true if said row exists or false if not.
===================================
¦ $xfi -> GotoNextCell($password) ¦
===================================
Selects the next cell if it exists. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns true if said cell exists or false if not.
======================================
¦ $xfi -> GotoPreviousRow($password) ¦
======================================
Selects the previous row in the database. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns true if said row exists or false if not.
=======================================
¦ $xfi -> GotoPreviousCell($password) ¦
=======================================
Selects the previous cell if it exists. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns true if said cell exists or false if not.
=================================
¦ $xfi -> GetLastRow($password) ¦
=================================
Returns the key of the last row in the database. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'. Returns false on fail.
==================================
¦ $xfi -> GetLastCell($password) ¦
==================================
Returns the key of the last cell. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
false on fail.
======================================
¦ $xfi -> ComparePassword($password) ¦
======================================
Compares $password with the DB password. Returns true if it matches, false if
not.
=================================================
¦ $xfi -> SetPassword($new_password, $password) ¦
=================================================
$new_password sets a new password. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
true on success or false on fail.
=====================================
¦ $xfi -> RemovePassword($password) ¦
=====================================
Removes the password from your DB. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
true on success or false on fail.
============================
¦ $xfi -> PasswordExists() ¦
============================
Returns boolean true if password has been set, false if not.
=========================
¦ $xfi -> GetLoggedIn() ¦
=========================
Returns boolean true or false for your current login status.
===============================
¦ $xfi -> GetTitle($password) ¦
===============================
Returns the title of the database. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
false on fail.
=======================================
¦ $xfi -> SetTitle($title, $password) ¦
=======================================
$title sets a new title for the database. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the table'.
Returns true on success or false on fail.
==============================
¦ $xfi -> GetPath($password) ¦
==============================
Returns the path of the database-file. $password is optional when 'you've performed
an object-wide login before' or 'no password has been set for the table'. Returns
false on fail.
=====================================
¦ $xfi -> SetPath($path, $password) ¦
=====================================
$path sets a new path for the database-file. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the table'.
Returns true on success or false on fail.
=======================================================
¦ $xfi -> RenameCell($old_name, $new_name, $password) ¦
=======================================================
$old_name defines the cell to rename. $new_name sets a new name for the cell.
$password is optional when 'you've performed an object-wide login before' or 'no
password has been set for the table'. Returns true on success or false on fail.
==========================================================
¦ $xfi -> RedefineType($cell_name, $new_type, $password) ¦
==========================================================
$cell_name defines the cell on which we want to redefine the data type. $new_type
sets the new type for the cell. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns
true on success or false on fail.
======================================================================
¦ $xfi -> NewCell($cell_name, $cell_type, $default_value, $password) ¦
======================================================================
$cell_name sets a new cell with the data-type $cell_type. $default_value is
optional and allows to fill the cell on each row with a standard value. $password
is optional when 'you've performed an object-wide login before' or 'no password
has been set for the table'. Returns true on success or false on fail.
=============================================
¦ $xfi -> DeleteCell($cell_name, $password) ¦
=============================================
$cell_name deletes a cell from the table. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the
table'. Returns true on success or false on fail.
=============================================
¦ $xfi -> GetCellName($cell_key, $password) ¦
=============================================
Returns the name of the cell with the key $cell_key. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'. Returns false on fail.
==========================================
¦ $xfi -> FirstRowToCellNames($password) ¦
==========================================
Assigns the values of the first row as cell names and removes the row from
the table. $password is optional when 'you've performed an object-wide login
before' or 'no password has been set for the table'. Returns true on success or
false on fail.
==========================================
¦ $xfi -> CellNamesToFirstRow($password) ¦
==========================================
Inserts a new first row, filling the cells with the cell names from the header.
$password is optional when 'you've performed an object-wide login before' or 'no
password has been set for the table'. Returns true on success or false on fail.
=============================
¦ $xfi -> SelectCell($cell) ¦
=============================
$cell selects the cell. $cell can be a cell name or a cell key. Returns true on
success or false on fail.
==============================
¦ $xfi -> ReIndex($password) ¦
==============================
Re-indexes the row keys. This is needed after deleting a row without enabling the
re-indexing option. Be aware that this will require you to keep track of your rows
yourself. $password is optional when 'you've performed an object-wide login before'
or 'no password has been set for the table'. Returns true on success or false on
fail.
===========================
¦ $xfi -> SelectRow($row) ¦
===========================
$row selects the row. $row must be a row key. Returns true on success or false on
fail.
===========================================================
¦ $xfi -> GetValue($cell, $row, $password, $show_noentry) ¦
===========================================================
$cell and $row are optional and allow you to directly move your position in the
database table [they are equal to the call of SelectCell() and SelectRow()].
$show_noentry (boolean true or false) defines if the XFI value for an empty cell
should be returned or not. The default value of $show_noentry is true. $password
is optional when 'you've performed an object-wide login before' or 'no password
has been set for the table'. Returns false on fail (note that if a cell has type
bool, GetValue() might return a valid boolean false).
======================================================
¦ $xfi -> StoreValue($value, $cell, $row, $password) ¦
======================================================
$value sets a new value for the currently selected cell in the row. $cell and $row
are optional and allow you to directly move your position in the database table
[they are equal to the call of SelectCell() and SelectRow()]. $password is optional
when 'you've performed an object-wide login before' or 'no password has been set
for the table'. Returns true on success or false on fail.
========================================
¦ $xfi -> GetRowTable($row, $password) ¦
========================================
Returns the row-table (array) of the currently selected row. $row is optional and
allows you to select the row [equal to the call of SelectRow()]. $password is
optional when 'you've performed an object-wide login before' or 'no password has
been set for the table'. Returns false on fail.
=====================================================
¦ $xfi -> StoreRowTable($rowtable, $row, $password) ¦
=====================================================
$rowtable (array) stores a row-table in the currently selected row. All old data
of the row will be replaced with the new one. $row is optional and allows you to
select the row [equal to the call of SelectRow()]. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'. Returns true on success or false on fail.
================================================
¦ $xfi -> AppendRowTable($rowtable, $password) ¦
================================================
$rowtable (array) appends a row-table with new data to the database. $password is
optional when 'you've performed an object-wide login before' or 'no password has
been set for the table'. Returns true on success or false on fail.
====================================================
¦ $xfi -> InsertRow($rowpos, $rowtable, $password) ¦
====================================================
Inserts an empty row or a rowtable at the position defined with $rowpos. $rowpos
must be a row key. $rowtable (array) is optional and allows to fill the cells of
the new row with row data directly. $password is optional when 'you've performed
an object-wide login before' or 'no password has been set for the table'. Returns
true on success or false on fail.
=============================
¦ $xfi -> NewRow($password) ¦
=============================
Appends a new, empty row to the database. $password is optional when 'you've
performed an object-wide login before' or 'no password has been set for the table'.
Returns true on success or false on fail.
================================================
¦ $xfi -> DeleteRow($row, $reindex, $password) ¦
================================================
$row must be a row key and deletes the row specified with the key. $reindex (true /
false) is optional and defaults to true. Re-indexing will get rid of all current
row keys and assign new ones. Sometimes you may need to keep the old keys for your
program code to execute properly - this is why you can disable re-indexing here.
However, keep in mind that it might lead to unexpected behavior of certain KX-Files
functions if the row keys don't increase properly. If you disable re-indexing, be
sure to call ReIndex() manually as soon as possible after deleting any rows.
$password is optional when 'you've performed an object-wide login before' or 'no
password has been set for the table'. Returns true on success or false on fail.
============================================================================================
¦ $xfi -> FindRow($search_string, $in_cell, $row_start, $row_end, $exact_match, $password) ¦
============================================================================================
Searches for the row that contains $search_string in the currently selected cell
and selects the first matching row. $in_cell is optional and allows you to directly
select the cell [equal to the call of SelectCell()]. $row_start and $row_end are
optional and define search range. They must be row keys. If they are false, the
range will be set to start at the first and/or to end at the last row. $exact_match
(true / false) defines if FindRow() should look for an exact or partial match.
$exact_match defaults to true. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns the
row key on success or false on fail.
=======================================================
¦ $xfi -> SortRows($cell_reference, $mode, $password) ¦
=======================================================
Sorts rows by cell contents. $cell_reference can be a string or an array. If
$cell_reference is an array, every cell stored in the array will be checked for the
sorting process. The optional $mode (XFSORT_UP / XFSORT_DOWN) sets the sorting mode.
$mode defaults to XFSORT_UP. $password is optional when 'you've performed an
object-wide login before' or 'no password has been set for the table'. Returns the
row key on success or false on fail.
=======================================================================================================
¦ $xfi -> MergeTables($merge_with_object, $rowpos, $check_headers, $this_password, $foreign_password) ¦
=======================================================================================================
Merges the parent table with the table of $merge_with_object. $merge_with_object
must be an instance of KXFiles. $rowpos is optional and allows to select a position
where foreign table should be integrated. If $rowpos is false, the foreign table
will be added at the end of the parent table. $check_headers (true / false) is
optional and defines if MergeTables() has to check for matching table headers
before it's going to merge the tables. $check_headers defaults to true, and if it's
true and the headers don't match, MergeTables() will exit with the return value
false. $this_password (parent table) and $foreign_password (foreign table) are
optional when 'you've performed an object-wide login before' or 'no password has
been set for the table'. Returns true on success or false on fail.
7) TABLE DEBUGGING TOOLS
======================================================
¦ $xfi -> EchoTable($row_start, $row_end, $password) ¦
======================================================
Echoes cells listed by rows in a similar way as PHP's print_r() does. $row_start
and $row_end are optional and define the search range. They must be row keys. If
they are false, the range will be set to start at the first and/or to end at the
last row. $password is optional when 'you've performed an object-wide login
before' or 'no password has been set for the table'.
8) PHP-GTK BINDINGS, EXTENDED CLASS
Only available when PHP-GTK is installed and loaded! If you want to use the
predefined GTK widgets of KX-Files, you need to construct your database object
with the GtkXFiles constructor instead of the KXFiles constructor. Example:
===========================================================================
¦ $xfi = new GtkXFiles($path, $cellnames, $celltypes, $title, $password); ¦
===========================================================================
Everything but the class remains the same.
===========================================================================================================
¦ $tableview = $xfi -> GtkTableView($onfileedit, $show_cells, $row_start, $row_end, $editable, $password) ¦
===========================================================================================================
Creates a GtkTreeView widget that interacts with your KX-Files table-object.
$onfileedit is optional and allows you to set a callback function for actions
that alter data in the table. $show_cells is optional and allows you to define
which cells may be displayed in the window table. The cells are separated by
comma. row_start and $row_end are optional and define the range to be displayed.
They must be row keys. If they are false, the range will be set to start at the
first and/or to end at the last row. $editable (true / false) defaults to true and
defines if the values of the table can be altered. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'.
=============================================
¦ $xfi -> GtkNewRow($onfileedit, $password) ¦
=============================================
Appends a new row to the TableView [that was created with GtkTableView()] and the
KX-Files table-object. $onfileedit is optional and allows you to set a callback
function for actions that alter data in the table. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'.
================================================
¦ $xfi -> GtkInsertRow($onfileedit, $password) ¦
================================================
Inserts a new row at the previously selected position (in both, TableView and the
KX-Files table-object). $onfileedit is optional and allows you to set a callback
function for actions that alter data in the table. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'.
================================================
¦ $xfi -> GtkDeleteRow($onfileedit, $password) ¦
================================================
Deletes the row at the previously selected position (in both, TableView and the
KX-Files table-object). $onfileedit is optional and allows you to set a callback
function for actions that alter data in the table. $password is optional when
'you've performed an object-wide login before' or 'no password has been set for
the table'.
==========================================================================================================
¦ $entry = $xfi -> GtkCellEntry($cell, $row, $dimensions, $nr_chars, $editable, $onfileedit, $password); ¦
==========================================================================================================
Creates a GtkEntry that is bound to the X-Files table. GtkCellEntry automatically
sets callbacks and rules for the entry. $cell and $row are optional and allow you
to select a position in the table. $dimensions is optional and must be an array.
It sets a size request for the entry widget. $nr_chars is optional and allows you
to set a character limit for the entry field. $editable defaults to boolean true.
If it's set false, the user won't be able to manipulate its content. $onfileedit
is optional and allows you to set a callback function for actions that alter data
in the table. $password is optional when 'you've performed an object-wide login
before' or 'no password has been set for the table'.
===================================================================================================
¦ $entry = $xfi -> GtkDateEntry($cell, $row, $order, $editable, $onfileedit, $jumpto, $password); ¦
===================================================================================================
Creates 3 GtkEntry widgets that are bound to a X-Files date cell. GtkDateEntry
automatically sets callbacks and rules for the entries. $cell and $row are optional
and allow you to select a position in the table. $order is optional and allows to
reorder the date entry fields. It defaults to "MM.DD.YYYY" and can be set to
"DD.MM.YYYY". $editable defaults to boolean true. If it's set false, the user won't
be able to manipulate its content. $onfileedit is optional and allows you to set a
callback function for actions that alter data in the table. $jumpto is optional and
defines a widget you could jump to after a date entry has been completed. $password
is optional when 'you've performed an object-wide login before' or 'no password has
been set for the table'.
9) GLOBAL CALLBACKS & FUNCTIONS FOR PHP-GTK
Only available when PHP-GTK is installed and loaded!
======================================================
¦ GtkEntry_numbers($widget, $event, $allow_negative) ¦
======================================================
Key action callback for GtkEntry to only allow number entries. $allow_negative
defaults to boolean false. If it's set true, negative number values will be
accepted.
=================================================
¦ GtkEntry_numeric($widget, $event, $positions) ¦
=================================================
Key action callback for GtkEntry to only allow numeric decimal entries.
$positions is optional and allows to check for how many positions after the
decimal dot the user can enter characters.
=========================================
¦ GtkEntry_jump($widget, $event, $next) ¦
=========================================
Key action callback for GtkEntry to jump from field to field when the user hits
"Return". $next holds the widget that should grab focus within this callback.
============================
¦ kxfi_error_dialog($text) ¦
============================
KX-Files error dialog. $text holds the message to show.
| |
