Cybiko SDK Help

Cybiko SDK 2.1

Introducing Cybiko SDK

  • Development Tools
  • Interface Standards
  • Tutorials
  • API Reference
CybikoTM is a multi-faceted computer capable of wireless, high-frequency, digital connections to other Cybiko computers. The possibilities are endless: you can play interactive games, chat wirelessly, find a friend, and, every single day, download a new application or game for free. However, despite the diversity and number of existing applications for Cybiko computer, for us programmers, there are never enough. We want to create our own, and this is where Cybiko SDK comes in.

The SDK features an extensive set of tools, ranging from the high-performance C compiler to the easy to use media converter. You can use numerous utilities to convert various data to CybikoTM formats and create archives. The SDK helps you manage projects as well. You can create complete, fully functional, applications either with C (supporting certain CybikoTM -specific extensions and capable of generating very tight code) or with assembler (having optimization options of its own!) –

now with the native code generator!
(Professional Edition only)

CyLandia is the world's first distributed artificial life simulator. It features cute creatures, called Cy-Bs, capable of teleporting to other computers and living there, remembering their friends on other computers, and reading (yes!) Internet-based newspapers and adequately reacting to its news. CyLandia is a good example of what you can do with the Cybiko SDK. Although the average CybikoTM application archive requires ten to twenty kilobytes, CyLandia has reached 200 kilobytes and it's still growing and in good shape - your larger apps will also work fine!

© 1999-2001. Cybiko, Inc. All rights reserved. More information...


Development Tools

Table of contents

  • Building Applications
  • Make Utility
  • Compiler driver
  • The Preprocessor
  • The Compiler
  • Cybiko Bytecode Interpreter
  • Utilities
  • Change Log
  • Make Utility
  • Known Problems (Current Wishlist)
    •
The Cybiko computer

Computer magazines present information about computers in a predictable fashion. Chances are, there is a table with processor, ROM, RAM, mass storage columns, then some other columns, then, of course, price. Presented that way, Cybiko's specifications will probably make you think were a throwback to the old days of Personal Computers. Indeed, Cybiko computer has 512k of RAM, 512k of flash memory, a 11-MHz processor, and a 4-color LCD display with 160x100 pixel resolution. You have to understand that Cybiko is not like other computers. Cybiko is a pocket-size, handheld, wireless computer. Two-way wireless communication is built into the design. The aim of this manual is to reveal the programming details to get you started writing applications for Cybiko computer so you can harness its unique features. This manual will explain what it takes to write your first "Hello, World!" program, what it takes to get the most out of the 11-Mhz processor, and what it takes to stuff your 1-megabyte masterpiece into our modest 512k.

Hardware specifications

Main Processor: | 32 bit, 11 MHz Hitachi H8S/2246
Coprocessor: | Atmel AT90S2313, 4 MHz
RAM: | 512 KB
Flash disk: | 512 KB, extendible up to 1 MB
LCD display: | 160x100 dots, 59x40 mm, 4 level grayscale
RF transceiver: | RF2915
Expansion cartridge slot: | 68-pin
PC connection socket: | RS232 serial port
Size: | 5.7" x 2.8" x 0.86"
Weight: | 4.3 oz

Features and figures

If you've programmed a wide range of computers (that is, not just PCs) then you probably can point out a counterpart of almost each and every feature of CybikoTM computers (with the exception of the wireless connection and the very way computers communicate). But Cybiko, and programming for Cybiko, is unique. Highlights include:
  • Simple and reliable wireless communication between computers. E.g., what does it take to send a data buffer from within some application to an (probably different) application on a different computer. It is as simple as calling one API function. Usually, there is no need to "initialize" some API, or to even "poll" or "enumerate" available computers; there is an easily and instantly accessible application called Finder which monitors available Cybiko computers in the vicinity, collects all necessary information (such as gender, habits, etc.) about them, and even sorts them out in the order set by the Cybiko computer owner. The reason behind this is simple: when a programmer requests the ID of the first computer in the Finder's list, he/she gets the ID of the computer most attractive to the owner of the local Cybiko computer! When sending a message, you do not need to reserve a special field for the sender ID, or invent your own way of guaranteed message delivery - all these goodies are already there!
  • The Cybiko operating system, CyOS, uses preemptive multitasking. Applications are, however, message-driven (much like in MS Windows), and CyOS keeps track of the time an application spends processing each message, and may even kill hung applications. It's important to keep in mind that there are other processes running concurrently with yours, and they consume system resources too. CyOS supports two types of modules: applications and dynamic libraries (compressed archives containing these modules have .app and .dl extensions, respectively). Both applications and dynamic libraries can export and import data and functions, and support both early and late binding. Module resources are also accessible to other modules via the part of the CyOS API that handles compressed archives.
  • Currently, Cybiko is built around the 11-MHz Hitachi H8S processor. It's a 32-bit processor and is, in many respects, more like the Motorola 68k than the Intel 80386. Importantly, it works in BE (Big-Endian) byte order mode and its register and instruction sets also bear some resemblance to those of the 68k. Although addressing is essentially 32-bit, actual address space is 24-bit, like in early 68k models. Since development is being done on PCs (and this is where most data files are being prepared also), you do have to take BE endianness into account. Moreover, this is not the only challenge - the H8S is physically unable to address a word located at an odd address.
  • As for processor performance, I would say you have more power than a 11-MHz 80386. Perhaps much more power. The key is instruction timing. While tinkering with an application, we were trying (really hard) to rework a little piece of code that used division (the infamous CPU time consumer). We did not succeed and, before giving up, looked at the H8S manual to see what would be the price of our failure good heavens, only 12 cycles! We could not believe it since that was the timing we were accustomed to with the 8-bit bus (more on this a bit later). The Hitachi's instruction timing is excellent: almost all arithmetic instructions take 1 cycle, multiplication 3 or 4, and division 12 or 20 cycles. Note that almost all instructions take 1 cycle longer if operating upon signed operands. Accessing data stored in RAM implies an overhead (more on this below).
  • On the other hand, there is no such thing as 32-bit multiplication or division; the constraints are the same as with Intel 8086 and 80286 processors, i.e. you can have a 32-bit product (but not multiplier), or use a 32-bit dividend (but not divisor). Of course, in C/C++ code, you may do whatever you want, but the compiler could then unroll some particularly optimistic operators into sequences of 16-bit multiplications or divisions. The H8S has eight 32-bit General Registers, also accessible as either 16 16-bit, or 16 8-bit registers. 32-bit registers can be used as either data or address registers.
Finally, the heart of the SDK is its C compiler, capable of producing very tight, and quite effective, code. The unique feature of the underlying virtual machine is its ability to operate upon registers (vs. "top of stack" for virtually any other vm, including that of JavaTM); this adds significant gain to overall performance. You may learn more about the Cybiko bytecode interpreter, as well as about the C compiler (that produces respectable code), in other sections of the manual.

Conclusion

The above described features could be summarized as follows:
  • We never experienced real problems with computer performance. Some tasks required clever programming, or reworking the algorithm (at most), but nothing was dropped due to performance issues. Cylandia runs its countless algorithms as methods compiled into bytecode (that is, it is made with this same SDK!) and it never hits its performance limit - we were even able to boost computation speed 10x when we were emulating "accelerated" gameplay.
  • We did experience problems with memory - but only in Cylandia, with its countless bitmaps, animations and cut scenes. "Normal" applications should not suffer like that.
  • Different endianness and alignment rules are either things which you ignore or the things that cause potential headaches - you decide.


Overview

Building Applications

Please note that you need Syspack 53 or higher to run games or applications made with Cybiko SDK on your Cybiko computer (in Main Desktop, press '?' to get to the System Information screen, and check the 'System Pack version' line).

There are two primary ways to build your application:

The Easy Way

The easiest way is to use the vcc command, for example:

vcc<filename1>.c [-o <filename2>.app]

The Harder But More Flexible Way
1.To use a vcpp preprocessor:
vcpp <filename1>.c [-I directory ] <filename1>.p

2. ... compile your file with a vcc1 compiler:
vcc1 <filename1>.p -o <filename1>.asm

3. ... assemble your file with vas assembler:
vas <filename1>.asm -o <filename1>.o

4. ... bind necessary files with vlink linker:
vlink -o bytecode.bin <filename1>.o [<other files>.o][...]

5. ... and, finally, prepare an application archive for the Cybiko computer:
filer a <app-filename>.app <resource-filenames> main.e bytecode.bin
Yet Another Way

There is one more way to compile your application: you may create a makefile and process it using vmake. To simplify this procedure, use this makefile as a template:

#-------------------------------------------------------------------------------------
#
# use 'vmake' (not 'make'!) to run this script!
#
#-------------------------------------------------------------------------------------

# set this to where Cybiko SDK actually resides
#CYBIKO_SDK = C:\Program Files\Cybiko Inc\Cybiko SDK

# you may also want to change this...

NAME = Fox_Hunting
OBJ = src/Foxhunt.o
RES = res/0.help res/bests.dat res/disable.mus res/filer.list res/fox.mus \
res/fox_hunting.pic res/intro.pic res/root.ico res/root.inf res/root.spl \
res/success.mus res/title.mus

PP = vcpp
CC = vcc1
AS = vas
LN = vlink
LD = filer
RM = vrm

.SUFFIXES : .c

all : $(NAME).app

# You must add to archive "$(CYBIKO_SDK)"/lib/main.e,
# your bytecode and application resources
# (*.pic better place first).
# *.spl - splash screen.
# *.help - help file.
# *.inf - information for programm manager.
# For more details see filer.exe manual.
$(NAME).app : tmp/bytecode.bin $(RES)
@echo building app archive...
@$(LD) a $@ @res/filer.list tmp/bytecode.bin "$(CYBIKO_SDK)"/lib/main.e

tmp/bytecode.bin : $(OBJ)
@echo linking ...
@$(LN) -o $@ src/*.o

.c.o :
@echo compiling $<...
@$(PP) -I"$(CYBIKO_SDK)"/inc $< | $(CC) | $(AS) -O -o $@

src/Foxhunt.o : src/Foxhunt.h

clean :
@echo cleaning...
@$(RM) -f tmp/*.* src/*.o $(NAME).app

new : clean all

Using MS Developer Studio as a Development Environment

1. | Make sure that Cybiko SDK 'bin' directory is listed in MSDEV executable search path (Tools -> Options -> Directories -> Executable files)
2. | Create new project. Go to File -> New... -> Projects, select 'Makefile' (important!) and fill in project name and location, then click 'OK'. For instance, name: 'highway_hitman', location: 'C:\Program Files\Cybiko\SDK\demos\highway_hitman'
3. | Fill in project options. Specify 'vmake' in the 'Command line' field, name of your application in the 'Output' field ('highway_hitman.app', for example) and rebuild target in the 'Rebuild All Switch' field (that should be 'new' for any makefile supplied with the SDK)
4. | Repeat previous step for the 'Release' options. You may want to use special targets in your makefile to build release version of your project.
At this point, your project should be ready — you can use 'Build' command to build your application. For your convenience, Cybiko SDK error and warning message format is made fully compatible with that of the Developer Studio, so that you could 'jump' to a source line for which a warning (or an error) message is issued — by simple clicking on a respective line in the output window (its 'Build' tab, if more exactly).


Make Utility

Table of Contents
  • Usage
  • Description
  • Options
  • How it works
  • Examples
  • Files
  • Diagnostics
  • Known Problems

Usage

vmake [-f makefile] [-dDinrst] [-p<0|1|2>] [target...] [macro=value ...]

Description

vmake takes a file of dependencies (a 'makefile') and decides what commands have to be executed to bring the files up to date. These commands are either executed directly from vmake or written to the standard output without executing them.

If no makefile is specified with a -f option, vmake reads a file named 'makefile', if it exists.

If no target is specified on the command line, vmake uses the first target defined in the first makefile.

vmake mostly conforms to the ANSI C standard.

Options
-f makefile
Use the description file 'makefile'. '-' as the makefile argument denotes the standard input.

-d
Display the reasons why vmake chooses to rebuild a target. All dependencies which are newer are displayed.

-dd
Display the dependency checks in more detail. Dependencies which are older are displayed, as well as newer.

-D
Display the text of the makefiles that are read from standard input.

-DD
Display the text of the makefiles and 'default.mk'.

-e
Let environment variables override macro definitions from makefiles. Normally, makefile macros override environment variables. Command line macro definitions always override both environment variables and makefile macros definitions.

-i
Ignore error codes returned by commands. This is equivalent to the special target .IGNORE:

-n
No execution mode. Print commands, but do not execute them. However, if a command line is an invocation of vmake , that line is always executed.

-r
Do not read in the default file 'default.mk'.

-s
Silent mode. Do not print command lines before executing them. This is equivalent to the special target .SILENT:.

-t
Touch the target files, bringing them up to date, rather than performing the rules to reconstruct them.

-p<0|1|2>
Pause after execution; 0 – never (the default), 1 – after an error, 2 – always.

macro=value
Macro definition. This definition remains fixed for the vmake invocation. It overrides any regular definitions for the specified macro within the makefiles and from the environment. It is inherited by subordinate MAKE's but act as an environment variable for these. That is, depending on the -e setting, it may be overridden by a makefile definition.

How it works

Makefiles
The first makefile read is 'default.mk', which can be located any-where along the PATH. It typically contains predefined macros and implicit rules. The default name of the makefile is 'makefile' in the current directory. An alternate makefile can be specified using one or more '-f' options on the command line. Multiple '-f's act as the concatenation of all the makefiles in a left-to-right order. The makefile(s) may contain a mixture of comment lines, macro definitions, include lines, and target lines. Lines may be continued across input lines by escaping the NEWLINE with a backslash (\). Anything after a "#" is considered to be a comment, and is stripped from the line. Completely blank lines are ignored. An include line is used to include the text of another makefile. It consists of the word "include" left justified, followed by spaces, and followed by the name of the file that is to be included at this line. Include files may be nested.

Macros
Macros have the form 'WORD = text and more text'. The WORD need not be uppercase, but this is an accepted standard. Later lines which contain $(WORD) or ${WORD} will have this replaced by 'text and more text'. If the macro name is a single character, the parentheses are optional. Note that the expansion is done recursively, so the body of a macro may contain other macro invocations.
e.g.
FLINTSTONES = wilma and fred
RUBBLES = barney and betty
BEDROCK = $(FLINTSTONES) and $(RUBBLES)
'$(BEDROCK)' becomes 'wilma and fred and barney and betty'

Also note that whitespace around the equal sign is not relevant when defining a macro. The following four macro definitions are all equivalent:

MACRO = body
MACRO= body
MACRO =body
MACRO=body

Macros may be added to by using the '+=' notation. Thus

FLINTSTONES += pebbles and dino

would be (given the examples above) the same as

FLINTSTONES = wilma and fred and pebbles and dino

Special Macros
MAKE
This normally has the value "vmake". Any line which invokes MAKE temporarily overrides the -n option, just for the duration of that one line. This allows nested invocations of MAKE to be tested with the -n option.

MAKEFLAGS
This macro has the set of options provided to vmake as its value. If this is set as an environment variable, the set of options is processed before any command line options. This macro may be explicitly passed to nested vmakes, but it is also available to these invocations as an environment variable.

SUFFIXES
This contains the default list of suffixes supplied to the special target .SUFFIXES:. It is not sufficient to simply change this macro in order to change the .SUFFIXES: list. That target must be specified in your makefile.

There are several dynamically maintained macros that are useful as abbreviations within rules. It is best not to define them explicitly.

$* - The basename of the current target.

$< - The name of the current dependency file.

$@ - The name of the current target.

The $< and $* macros are normally used for implicit rules. They may be unreliable when used within explicit target command lines.
Targets
A target entry in the makefile has the following format:
target ... : [dependency ...]
[rule]/
...
Any line that does not have leading whitespace (other than macro definitions) is a 'target' line. Target lines consist of one or more filenames (or macros which expand into same) called targets, followed by a semi-colon (:). The ':' is followed by a list of dependent files.

Special allowance is made on MSDOS for the colons that are needed to specify files on other drives. For example, the following will work as intended:
c:foo.bar : a:fee.ber

If a target is named in more than one target line, the dependencies and rules are added to form the target's complete dependency list and rule list.The dependents are ones from which a target is constructed. They in turn may be targets of other dependents. In general, for a particular target file, each of its dependent files is 'made', to make sure that each is up to date with respect to it's dependents.

The modification time of the target is compared to the modification times of each dependent file. If the target is older, one or more of the dependents have changed, so the target must be constructed. Of course, this checking is done recursively, so that all dependents of dependents of dependents of ... are up to date.

To reconstruct a target, vmake expands macros, strips off initial whitespace, and either executes the rules directly, or passes each to a shell or COMMAND.COM for execution. For target lines, macros are expanded on input. All other lines have macro expansion delayed until absolutely required.

Special Targets
.DEFAULT:
The rule for this target is used to process a target when there is no other entry for it, and no implicit rule for building it. vmake ignores all dependencies for this target.

.DONE:
This target and its dependencies are processed after all other targets are built.

.IGNORE:
Non-zero error codes returned from commands are ignored. Encountering this in a makefile is the same as specifying -i on the command line.

.INIT:
This target and its dependencies are processed before any other targets are processed.

.SILENT:
Commands are not echoed before executing them. Encountering this in a makefile is the same as specifying -s on the command line.

.SUFFIXES:
The suffixes list for selecting implicit rules. Specifying this target with dependents adds these to the end of the suffixes list. Specifying it with no dependents clears the list. In order to add your own dependents to the head of the list, you could enter:
.SUFFIXES:
.SUFFIXES: .abc $(SUFFIXES)
Rules
A line in a makefile that starts with a TAB or SPACE is a shell line or rule. This line is associated with the most recently preceding dependency line. A sequence of these may be associated with a single dependency line. When a target is out of date with respect to a dependent, the sequence of commands is executed. Shell lines may have any combination of the following characters to the left of the command:

@ will not echo the command line.
- vmake will ignore the exit code of the command, i.e. the ERRORLEVEL of MSDOS. Without this, vmake terminates when a nonzero exit code is returned.
+ vmake will use COMMAND.COM to execute the command.

If the '+' is not attached to a shell line, but the command is a DOS command or if redirection is used (<, |, >), the shell line is passed to COMMAND.COM anyway.

Implicit Rules
Implicit rules are intimately tied to the .SUFFIXES: special target. Each entry in the .SUFFIXES defines an extension to a filename which may be used to build another file. The implicit rules then define how to actually build one file from another. These files are related, in that they must share a common basename, but have different extensions.

If a file that is being made does not have an explicit target line, an implicit rule is looked for. Each entry in the .SUFFIXES: list is combined with the extension of the target, to get the name of an implicit target. If this target exists, it gives the rules used to transform a file with the dependent extension to the target file. Any dependents of the implicit target are ignored.

In the following example, the .SUFFIXES: list is .c .y .l, and the target file is fred.o which does not have a target line. An implicit rule target '.c.o' is constructed and searched for. If it does not exist, the next suffix is tried. If the implicit rule target does exist, vmake looks for a file 'fred.c'. If this file does not exist, the next extension is tried. If 'fred.c' does exist, then the associated rules are executed to create fred.o from fred.c, presumably invoking the C compiler.

If the next extension must be tried, vmake reiterates the above with target '.y.o' and a file named 'fred.y', and potentially with '.l.o' and 'fred.l'.

Examples

This makefile says that pgm depends on two files a.obj and b.obj, and that they in turn depend on their corresponding source files (a.c and b.c) along with the common file incl.h.
pgm : a.obj b.obj

$(CC) a.obj b.obj -o $@

a.obj: incl.h a.c

$(CC) -c a.c

b.obj: incl.h b.c

$(CC) -c b.c
The following makefile uses implicit rules to express the same dependencies.
pgm : a.obj b.obj

pgm : a.obj b.obj

$(CC) a.o b.o -o $@

a.obj b.obj: incl.h

Files

makefile
Current version(s) of make description file.

default.mk
Default file for user-defined targets, macros, and implicit rules.

Diagnostics

vmake returns an exit status of 1 when it halts as a result of an error. Otherwise it returns an exit status of 0.
Badly formed macro
A macro definition has been encountered which has incorrect syntax. Most likely, the name is missing.

cannot open file
The makefile indicated in an include directive was not found or was not accessible.

Don't know how to make target
There is no makefile entry for target, none of vmake 's implicit rules apply, and there is no .DEFAULT: rule.

Improper Macro
An error has occurred during macro expansion. The most likely error is a missing closing bracket.

rules must be after target
A makefile syntax error, where a line beginning with a SPACE or TAB has been encountered before a target line.

too many options
vmake has run out of allocated space while processing command line options or a target list.

Features

vmake allows spaces as well as TABs to introduce shell command lines.

Known Problems

vmake does not allow a target line to end with a semi-colon (;) and a command. All commands must be on separate lines.

Target lines cannot use the double colon (::) syntax. Once a dependency is made, vmake assumes that the dependency file is present for the remainder of the run. If a rule subsequently removes that file and future targets depend on it's existence, unexpected errors may result.

Sometimes vmake gets confused when searching for implicit rules, and uses several rules instead of a single rule. For example, the two rules .c.o and .l.c may be used, rather than the more direct .l.o rule.

The -f options are included in MAKEFLAGS for subordinate vmakes. These are safely ignored, as long as $(MAKEFLAGS) is NOT specified on the $(MAKE) command line.

The following flags are NOT supported:
-k
When a nonzero error status is returned by a command, abandon work on the current target, but continue with other branches that do not depend on this target.

-p
Print out the compete set of macro definitions and target

-P
Report dependencies recursively to show the entire dependency hierarchy, without rebuilding any targets.

-q
Question mode. VMAKE returns a zero or non-zero status code, depending on whether or not the target file is up to date.

-S
Undo the effect of the -k option. Stop processing when a non-zero exit status is returned by a command.
The following special targets are NOT supported:

.KEEP_STATE:
.MAKE_VERSION:
.PRECIOUS:
.SCCS_GET:


vcc.exe driver

Compiler Driver

Table of Contents
  • Usage
  • Description
  • Options
  • Known Problems
Usage

vcc [-D name [ = value ] ] [-U name ] [-V <#ver>] [-A] [-d] [-o file_name] [-h] [-c] [-K] [-E] [-S] [-I directory] [-v] [-O] [-L] [-Vn] [-A<libpath>] [-Rn] [-wn] [-Wn] [infile]

Description

vcc reads a C source file and feeds it to the preprocessor, compiler, assembler and, if necessary, the filer. If no file arguments are given, vcc displays "help" details. Filenames that are not clearly specified are defined by the following rules:
  • By the name of an input file (if there is only one file);
  • By the name of an output file;
  • By the name of the first input file
and have the “.bin” extension.

After assemblage, if the extension of the output file is ".app", it is an archive containing the file along with the file "main.e”. The "main.e" file is taken from the ($CYBIKO_SDK)\lib directory.

If the directory ($CYBIKO_SDK)\inc exists, adds it to the list of directories that are searched when the #include "..." and #include <...> directives are used.

Files from the infile list with an unidentified extension (if the output file has an ".app" extension) are added to the archive.

Options

-D name [= value ]
Define the name as if the programmer wrote "#define" name value at the start of the first file. If "= value" is not given, a value of "1" will be used.

-U name
Undefined the name as if "#undef" name were used. On non-Unix systems, "name" will be forced to upper-case.

-d
Disassemble compiled program to stdout

-o file_name
Specify output file name.

-h
Display help.

-c
Compile only

-K
Keep temp files.

-E
Keep post-pre-processor file.

-S
Keep assembler files.

-I directory
Path for include files for pre-processor.

-v
Verbose.

-O
Optimization.

-L
link in library module (a.k.a. 'static linkage').

-V <bytecode_version_num>
Compatibility with bytecode.dl of mentioned version. Number of version and list of changes you can find here.

-A<libpath>
Specify library search path

-Rn
Specify root.inf lookup/generation mode:
0 - neither generate nor check for presence
1 - check but do not generate (default)
2 - generate automatically

-n
generate 'native' code (that is, CPU opcodes instead of bytecodes for the virtual machine); programs generated with this switch will run much faster, though will be considerably bigger than their 'bytecode' counterparts; please note that the main() function will always compile into bytecode, disregarding the '-n' switch (Professional Edition only).

-W(n)
Set warning level (default n=1)

-w(n)
Issue no more than n warnings (default n=8)

Known problems

There are problems connected with all stages of code generation (see vcpp, vcc1, vas, filer), because this unit is only the shell.


The Preprocessor

Table of Contents
  • Usage
  • Description
  • Options
  • Known Problems

Usage

vcpp [-C] [-D name [ = value ] ] [-E] [-I directory ] [-N] [-S text ] [-U name ] [-P] [infile [outfile] ]

Description

vcpp reads a C source file, expands macros and include files, and writes an input file for the C compiler. If no file arguments are given, cpp reads from stdin and writes to stdout. If one file argument is given, it is assumed to be the input file, while two file arguments will be the input and output files. The file name "-" is a synonym for stdin or stdout as appropriate.

There are no target-specific variables defined, since they are expected to be provided using the -D option from the compiler driver. The following are always available unless -N was specified twice: __FILE__ , __LINE__ , __DATE__ and __TIME__ .

vcpp mostly conforms to the ANSI C standard.

Options
-C
If set, source-file comments are written to the output file. This allows the output of cpp to be used as the input to a program, such as lint, that expects commands embedded in specially-formatted comments.

-D name [= value ]
Define the name as if the programmer wrote #define name value at the start of the first file. If = value is not given, a value of 1 will be used.

-E
Always return "success" to the operating system, even if errors were detected. Note that some fatal errors, such as a missing #include file, will terminate cpp, returning "failure" even if the -E option is given.

-I directory
Add this directory to the list of directories searched for #include "..." and #include <...> commands. Note that there is no space between the "-I" and the directory string. More than one -I command is permitted. On non-Unix systems "directory" is forced to upper-case.

-N
cpp normally predefines some symbols defining the target computer and operating system. If -N is specified, no symbols will be predefined. If -N -N is specified, the "always present" symbols, __LINE__, __FILE__, and __DATE__ are not defined.

-S text
cpp normally assumes that the size of the target computer's basic variable types is the same as the size of these types on the host computer. (This can be overridden when cpp is compiled, however.) The -S option allows dynamic respecification of these values. "text" is a string of numbers, separated by commas, that specifies correct sizes. The sizes must be specified in the exact order:

char short int long float double

If you specify the option as "-S*text", pointers to these types will be specified. -S* takes one additional argument for pointer to function (e.g. int (*)())

For example, to specify sizes appropriate for a PDP-11, you would write:
c s i l f d func -S1,2,2,2,4,8, -S*2,2,2,2,2,2,2

Note that all values must be specified.

-U name
Undefine the name as if #undef name were given. On non-Unix systems, "name" will be forced to upper-case.

-P
Don't output # line lines and keep heading white space in lines. This option is useful if the output of cpp is fed to a program which would be confused by those lines.

-M [switch]
Turn itself into dependencies' generator. Valid switches are:
(none) print to 'makedeps'
+ process system includes
.ext assume object file extension is .ext
path print to <path> rather than to 'makedeps'

Known Problems

Many, and probably more than you want to know about. Here are a few: The #if expression processor uses signed integers only. I.e, #if 0xFFFFu < 0 may be true.

If you write

#define string(arg) "arg"
... string("foo") ...

this implementation generates "foo", rather than the strictly correct ""foo"" (which will probably generate an error message).

vcpp does not do inside-out expansion, but outside-in. Unless you start to use quoting, you probably won't see the difference.

There are no trigraphs implemented.


The Compiler

Table of Contents
  • Usage
  • Description
  • Features
  • Options
  • Known Problems

Usage

vcc1.exe [-i] [-h] [-V <#ver>][-Wn] [-wn]<infile> [-o <outfile>]

Description

vcc1.exe reads a C file after it has been preprocessed, performs optimization, and generates an input assembler file. If no file arguments are given, vcc1.exe reads from stdin and writes to stdout. If one file argument is used, it is assumed to be the input file.

vcc1.exe performs optimization of C code using modern optimization methods such as constant expression folding, jump around jump elimination, duplicate string elimination, register allocation and many others.

The compiler does not generate native code for the HITACHI processor. For more details see Cybiko Bytecode Interpreter

vcc1.exe mostly conforms to the ANSI C standard.

Features

All number values in Cybiko’s version of C language are signed.

Besides common features of the ANSI C languages, some features are added in Cybiko’s version of the C language.
1. SWITCHFAST keyword.
2. EXPORT keyword.
In Cybiko’s version of C language it is possible to declare any function as exported by using EXPORT keyword.
Syntax: EXPORT <export_index> <function description>

Export index is a zero-based number of this function in the export table. The first allowed index for user’s functions is 3 (three). That’s important to understand: functions are exported not by name, but by their indexes ONLY.

3. IMPORT keyword.
Exported functions may be imported in the user’s program by using IMPORT keyword.
Syntax: IMPORT <import_index> <function description>

It’s important to understand, that, if you wish to import a function that was exported before with N export index, you have to use N as the import index too! Function descriptions in both cases have to be equal, the user may change only the NAME of the importing function! The user does not have to change the type of function, the number of arguments or the type of arguments.

4. Inheritance of structures
In Cybiko’s version of the C language, an inheritance of structures is realized. If you need, you can write:
struct my_struct1 : public my_struct2 { field_declaration_list };
or
struct my_struct1 : public my_struct2;

In this example my_struct1 is a descendant of my_struct2 and vice versa my_struct2 is a ancestor of my_struct1.

Options

-i
Get information about the compiler version.

-h
Print help message.

-o <outfile>.asm
Use <outfile>.asm as the name of the output assembler file.

-W(n)
Set warning level (default n=1)

-w(n)
Issue no more than n warnings (default n=8)

-V <bytecode_version_num>
Compatibility with bytecode.dl of mentioned version. You can find the version number and a list of changes here

-n
generate 'native' code (that is, CPU opcodes instead of bytecodes for the virtual machine); programs generated with this switch will run much faster, though will be considerably bigger than their 'bytecode' counterparts; please note that the main() function will always compile into bytecode, disregarding the '-n' switch (Professional Edition only).

Known problems

1. The size of the output file for downloading into Cybiko computer shouldn't be bigger than 64K.

For a detailed list of compiler bugs, see Known problems


Cybiko Bytecode Interpreter

Table of Contents

  • Reasons For Inventing The Wheel
  • Design Decisions
  • Structure And Use of Bytecode Modules
  • Internal Register Assignments
  • Assembler
  • Assembler Directives
  • Instruction Operands
  • Instruction Set
  • Recent Additions
  • What Will Come Next

Reasons For Inventing The Wheel

The Cybiko computer is built around the Hitachi H8S processor which, from the programmer's point of view, has many nice features, most notably excellent instruction timing, 32-bit architecture (including a "flat" address space), and plenty of registers. When you need to squeeze the last cycle out of some time-critical piece of code, control hardware, or manage power savings, the H8S is great. But when it is necessary to come up with short programs, the H8S fails. There are several reasons for this:

1. The H8S is a successor to a 16-bit processor, designed to maintain maximum compatibility with its predecessor. These Hitachi processors might appear to be like the Intel i80x86 processors at first glance. But while (in 32-bit "flat" mode) Intel "sacrificed" 16-bit instructions (whenever you employ an instruction that operates upon 16-bit operand[s], it gets prefixed with an extra byte), Hitachi "sacrificed" some 32-bit instructions. Most notably, 16-bit push/pop take 2 bytes each, while their 32-bit counterparts take 4 (!) bytes each. And remember, these are the instructions that the GNU C compiler uses for passing all function arguments to vararg functions and all arguments (except the first 3) to other functions.

2. The H8S has an extensive set of instructions for operating upon bits, bit masks, etc., and these instructions have rather short opcodes. It is amazing what one can do with a carry bit. This is great for operating system (especially device driver) writers, and for die-hard assembler addicts. But from the compiler's perspective, they are almost useless, and simply eat up opcode space, making "useful" (from the compiler's point of view) opcodes much longer.

3. The H8S has a RISC-alike architecture in many respects. First and foremost, the lengths of all its opcodes are multiples of 2 (the length of a machine word). From the perspective of optimizing an opcode set in terms of average code length (by Hitachi engineers), this was a bad thing. RISC architecture also implies that, in any opcode, all involved registers must be denoted explicitly — all you can do with the memory operand is load or store it.

4. It seems that in the famous "time vs. space" tradeoff, Hitachi engineers have always favoured time. The most notable example is the execution flow control instruction subset. There are two "flavours" of most such opcodes: "branches" (opcode names are some derivations of 'branch', opcodes are 2-byte and employ 8-bit relative displacements) and "jumps" (derivations of 'jump', 4-byte, 24-bit displacements, respectively). The funny thing is that, while instructions must be aligned upon 2-byte (word) boundaries, "branch" opcodes address bytes, not words. That is, displacements stored within instructions never have its lower bit set. Even if you (via some cheating) store 1 there, it will be ignored by the internal processor logic. So why not store disp/2 and "expand" it (i.e. left-shift) just before utilization, enlarging byte-addressable range (and thus reducing the need for the dword-sized jumps) by a factor of two? It seems like this would require one extra processor cycle.

The features mentioned above are great if you're dealing with a controller, firmware for the "frozen" built-in system, or just something time-critical. But Cybiko features an extensive object-oriented OS (with pre-emptive multitasking), GUI, an extensive and ever-growing set of applications, and much more. And these features, and much more, must fit in only 250k RAM. So, we started looking for something less expensive in terms of consumed memory, and came up with our bytecode interpreter (which, BTW, currently uses only 950 bytes by itself!).

The above list could be expanded, of course, but there is also another big reason for implementing a bytecode interpreter, which can be explained in even greater detail. Fortunately, Sun Microsystems did the boring work for us by advertising their Java virtual machine with a bytecode interpreter of its own. So to learn more about the huge and undisputed advantages :-) of interpreted vs. native code, you're probably better off with Sun's The Java Language Environment: A White Paper (by James Gosling and Henry McGilton).

Design Decisions

A good interpreter has to be small and fast. These days, "small" is no longer considered a mandatory property, but things look very different when all you have is 250k of RAM shared with other (potentially even more demanding) applications running concurrently. So we have taken some steps to pursue both goals; specifically:

1. Our interpreter, as a virtual machine, works with registers, not with a [virtual] stack. There are two virtual registers, R0 and R1 (which correspond to real registers er0 and er1 of the H8S processor) which get used as operands. This does not lead to opcode bloat, however, each register has a hard-coded role — in other words, no single opcode contains a "register bit". For example, push implies register R0, pop implies register R1, and so on. This may sound weird, at first, but there are very clever ways to make use of such opcodes, and our existing C compiler proves that. As for opcode implementations, please consider this one:
add:
add.l er1, er0 ; 2 bytes, 1 cycle
bra scheduler ; 2 bytes, 2 cycles

It is that simple.

2. There is no translation layer between CyOS and the hardware on one side, and the bytecode interpreter on the other. For example, push, pop, calln, and retn. Opcodes make use of the regular stack and not the emulated one. Upon calls to CyOS and so called extension functions (see below) which expect the first 3 parameters to be in registers, those parameters' values get placed into the proper registers as a result of standard expression evaluation sequences (e.g. extension functions, written in "regular" C, expect their 3-rd argument to be 'this' and expect it to be passed in register er2, but bytecode interpreter always keeps 'this' in er2). That means that the interpreter does not have to move registers' values around before each call. Thus the bytecode interpreter and the rest of the system are pretty well integrated.

3. The bytecode interpreter has neither 'stack frame pointer' nor 'code buffer pointer'. For those of you familiar with the i80x86 processors: 'stack frame pointer' used to be BP in 16-bit programs, and EBP in 32-bit. Compiler writers managed to always compute local variables' addresses relative to ESP, and thus freed EBP for use as a general register. In GNU C/C++, this is known as 'omit frame pointer' optimization. Our C compiler always does this optimization, so we dropped the very notion of 'stack frame pointer' out of our virtual machine specification.

Almost the same applies to 'code buffer pointer' - there is no such thing. Even such an instruction as leag.u contains displacement relative to the very next instruction, not any "absolute" offset. Other instructions, such as calln.s and jump.c are similar in this respect. In other words, the code is essentially position-independent (a.k.a. PIC).

4. The maximum size of a bytecode module is 64k; therefore, "local" address space is essentially 16-bit and, consequently, "static" offsets (including those used in calln.s opcode) are 2-byte. Furthermore, stack frames are addressed with unsigned 1-byte displacements (thus, a function cannot have more than((255-4-1)&~3)==248 bytes of arguments and 'auto' variables in total); objects are also addressed with unsigned 1-byte displacements (therefore, objects cannot be larger then 256 bytes; in other words, no more than 256 bytes are addressable via 'this', but objects themselves could be of any size up to 64k). But — as soon as any address gets loaded into a register (say, as a result of leal.b bytecode execution, which effectively sums 1-byte offset it contains and current value of stack pointer and places result in R0), it becomes a valid 32-bit address, fully compatible with those used by the rest of the system.

5. There are bytecodes for "object" commands, that is, opcodes that operate upon data addressed relative to the special 'this' pointer. In other words, there are provisions for object-oriented languages, such as C++. The current implementation of C has some OO extensions implemented via the use of these opcodes (which save considerable space). See leat.b for more information.

6. Not all arithmetic opcodes are 32-bit. Multiplication and division are essentially 16-bit in that if their operands do not fit within the -32768..32767 range, results are unpredictable (this does not apply to the dividend). This is a design decision.

7. Unsigned data types are not supported, just like in Java. The only supported data type types are signed char, short (synonym for int), and long. However, unsigned shift right, and specialized Unicode character types found in Java are not supported in the Cybiko bytecode interpreter. Note that the H8S has a 24-bit address space and no virtual memory, so any address is guaranteed to have 8 higher bits clear; in other words, addresses could safely be treated as signed entities and compare correctly. We used this fact for major optimization: we excluded all opcodes for unsigned comparisons.

8. Opcodes are bytes, so there may be up to 256 of them. The thing is that we take the famous "profile anything, assume nothing" rule quite seriously. From this perspective, we want to build as perfect an instruction set as possible while maintaining maximum (including full backward) compatibility with current implementation. Therefore, we decided to implement a minimalist set of opcodes, wait until large pieces of software which make use of that set appear, and then "profile" them to see what bytecode sequences are most used, and then make them into new bytecodes. Similar approaches already proved to be highly efficient with our proprietary compressor.

9. The bytecode interpreter is fully re-entrant. Any number of applications executing bytecode modules (even with different sets of extension functions) share a single in-memory image of the respective dynamic library (bytecode.dl).

Structure And Use of Bytecode Modules

The structure of a module is simple. At the very beginning, there is a table of even number 16-bit words. In other words, there is a word, then some number of pairs of words are followed by one more word. The very first word is an offset to the module entry point: function main(), or whatever you call it; please see the VCC1 compiler documentation for more info on how that compiler handles module entry point (however, your treatment may vary; see below). Pairs are offset (again, relative to the start of the module) from data and code for "exported" objects, respectively (remember — all words, including double words, are stored in BE order!). The very last word is a "terminating NULL". Currently, the following tasks are up to the programmer:

1. How to load the module into memory. You should probably load it like any other resource - from the .app or .dl application archive. You may then keep it in memory (and keep p-code running) until your program terminates, or you may free it upon losing focus (thus effectively suspending p-code execution) and then re-load upon getting focus again.

2. How to interpret data and code pointed to by those offsets at the beginning of the module. For example, Cylandia treats the first offset as the module initialization function's offset (which contains relocation records and objects' ctors), and treats remaining offsets (except for the very last one, of course) as offsets to data and code of game actors. Our C compiler thinks of them as exported structures and respective exported methods.

The only way to execute bytecodes is to call the vm_exec family function found in the bytecode.dl library, like this (below, we assume that entire module got loaded into 'word_t* buff'):

/* 1) call module initialization routine */

vm_exec( NULL, /* no active objects/actors yet */
(byte_t*) bytecode +
bytecode[ bytecode[ I_FIRST_EXPORT ] + I_STARTUP ], /* startup code */
extension functions ); /* functions imported by p-code*/

/* 2) enter main loop */

vm_exec_3( NULL, /* no active objects/actors yet */
(byte_t*) bytecode +
bytecode[ bytecode[ I_FIRST_EXPORT ] + I_MAIN ], /* main(): module entry point */
extension functions, /* functions imported by p-code*/
argc, argv, TRUE); /* arguments */

/* 3) call module cleanup routine */

vm_exec( NULL, /* no active objects/actors yet */
(byte_t*) bytecode +
bytecode[ bytecode[ I_FIRST_EXPORT ] + I_CLEANUP ], /* cleanup code */
extension functions ); /* functions imported by p-code*/

Important note: all functions that are called via vm_exec() must return with retf opcode (in other words, they're considered far, as opposed to near functions callable via calln.s).

The very last argument to vm_exec() is the address of the table of functions prototyped as follows (also, see callx.b opcode description):

typedef dword_t (*import_t)( dword_t arg0, dword_t arg1, void* this_ptr );

import_t extension_functions[] = { /* ... */ };

The primary use of extension functions is for implementation of time-critical pieces of code and filling in the gaps which currently exist in the interpreter's import abilities. For example, currently there is no way to import CyOS' global variables, so you'll probably have to provide an extension function which returns the address of a variable (say, a font handle) to get access to it.

Please see the attached example program for further details.

Internal Register Assignments

Internally, bytecode interpreter (i.e. vm_exec() function found in the bytecode.dl dynamic library) uses the following register assignments:

er0 virtual register R0 (accumulator/pointer for indirect loads),

er1 virtual register R1 (aux data register/pointer for indirect saves),

er2 'this' for the object/actor/struct being processed,

er3 scratch register,

er4 table of extension functions (caller-supplied),

er5 table of built-in opcodes,

er6 p-code instruction pointer (static data/code space),

er7 stack pointer.

Assembler

The bytecode assembler - vas utility, understands the following options:

-i display version information (logo),

-d disassemble its own output to stdout (check output integrity),

-h display help (usage info, currently quite terse, to say the least),

-o outfile name output file (stdout by default).

-O Optimize output assembler code

-v Verbose mode – statistic messages about module to be compiled will be generated

If no options are given, vas tries to read stdin and to write to stdout, don’t optimize output code and don’t write statistic messages. Preferable extension for the output file is .bin, which stands for binary. While parsing input:

  • empty lines are ignored,
  • semicolon (;) is considered a comment character - the semicolon itself and everything up to the end of line is treated as a comment and is ignored,
  • if first non-blank character on the line is period (.) that line is considered to be an assembler directive,
  • otherwise, the line must contain a valid instruction code.
  • only one instruction name may be placed in one string.

Assembler Directives

Note: forward references (i.e. references to labels which have not been defined yet) are OK. Moreover, the assembler operates so that even resolving backward references is always postponed until the second pass.

.ln <line_number>

Associates all the following instructions (until next .ln directive) with a particular line number within source code in a higher-level language (say, C, C++, BASIC, Pascal, etc.) Compilers should use this directive extensively while emitting code so that the assembler can report errors and other problems in association with the source line that caused them.

.label <global_label>

Introduces a global label. Label name is a number in range [99, 32768]. It does not matter (at all) what that label denotes — program code or data, or even something else (like control information); the label is just assigned the current value of the Program Counter (PC). Two, or more, labels on sequential lines are OK; these labels will be identical.

.disp <global_label> <displacement>

Allocates 2 bytes and then stores there the unsigned distance from the current position of the Program Counter forward to the label <global_label> + <displacement>. I.e. the following sequence

.disp 555 0
.label 555

stores 0, not 2; while the following sequence stores 7:

.disp 333 0
.skip 7
.label 333

Currently, this directive is used in conjunction with the switch opcode only.

.ldisp <global_label> <displacement>

Allocates 4 bytes and then stores there the distance from the current position of the Program Counter to the label <global_label> + <displacement>.

.offset <global_label>

Allocates 2 bytes and stores an absolute offset to the label <global_label>. This opcode is currently used for building export tables only.

.even

If current value of Program Counter is an odd number, then this directive emits zero bytes. Please note that there is no need to align code, so this directive is only useful for data elements bigger then one byte.

.skip <number_of_bytes>

Advances Program Counter by specified <number_of_bytes> (i.e. allocates<number_of_bytes> zero bytes).

.byte <number>

Emits byte <number>. Preferred way to initialize static data.

.word <number>

Emits word <number>.

.string <text_in_double_quotes>

Emits string literal with the value <text_in_double_quotes>, plus terminating 0. Unfortunately, there is currently no way to escape any symbols, notably newline and quotable quotation marks. As a workaround, the .byte directive could be used to emit any bytes, but please be warned that, in the future, characters may no longer be single bytes.

.bss

Starts the 'bss' (Blank Storage Segment) segment. Preferred place for uninitialized global variable.

.text

Starts segment of code.

.data

Starts segment of data.

.rodata

Starts segment of data. Duplicate segments of this type will be merged by vlink.

.public <label> "<name>"

Declares public symbol for using in other modules.

.extern <label> "<name>"

Declares extern symbol used in module.

.end

Specifies logical end of the source file. Source files that do not use this directive may not compile with future versions of the assembler.

Instruction Operands

All bytecodes have one explicit operand, at most. However, assembler instructions for some of them seem to allow for one extra argument (see below). Please note that this is only a notation device — a way to tell assembler to adjust target address after converting label number or base address into a final offset (stack-, object-, or buffer-relative).

Suppose the Cybiko C compiler sees something like this:

int my_array[ 3 ];
...
my_array[ 2 ] = 1;

Obviously, there is no need to load index, scale it (since array elements are word-sized), then load address of the array, then add it to scaled index, etc. Instead,
our compiler will produce something like this:

.label 777 ; my_array
.skip 6
...
leag.u 777 4 ; my_array
move
load1
storeis

Here, 777 is label number (ordinal), 6 is the size of my_array[], and 4 is extra displacement relative to the label 777. Note that assembler will turn 'leag.u 777 4' into a single opcode followed by the word-sized displacement (hence .s suffix).

Note that instruction suffixes designate optional data that may follow (and not the size of the operands):

.c char (that is, signed byte),
.b byte (unsigned byte),
.s short (16-bit signed word),
.u unsigned short (16-bit unsigned word),
.w word (16-bit unsigned word),
.l long word (32-bit signed double word).

Instruction Set

seteq

Compares R0 to R1, sets R0 to 1 if registers are equal, or to 0 otherwise.

setlt

Compares R0 to R1, sets R0 to 1 if R1 is less than R0, or to 0 otherwise.

setle

Compares R0 to R1, sets R0 to 1 if R1 is less than or equal to R0, or to 0 otherwise.

setgt

Compares R0 to R1, sets R0 to 1 if R1 is greater than R0, or to 0 otherwise.

setge

Compares R0 to R1, sets R0 to 1 if R1 is greater than or equal to R0, or to 0 otherwise.

setz

Tests R0 and sets it to 1 if it was zero, or to 0 otherwise, effectively performing 'logical not' upon contents of R0. Roughly equivalent to the following opcode sequence: move load0 seteq.

setnz

Tests R0 and sets it to 1 if it was non-zero; roughly equivalent to the following opcode sequence: move load0 setne. This is effectively 'convert to boolean' operator performed upon contents of R0.

cmpe.c <num>

Compares R1 to signed byte <num> (-128..127), sets R0 to 1 if they are equal, or to 0 otherwise. Same as the 'load.c <num> seteq' sequence but more efficient.

cmpe.s

Compares R1 to signed word <num> (-32768..32767), sets R0 to 1 if they are equal, or to 0 otherwise. Same as the 'load.s <num> seteq' sequence but more efficient.

cmpe.l <num>

Compares R1 to signed double word <num>, sets R0 to 1 if they are equal, or to 0 otherwise. Same as the 'load.l <num> seteq' sequence but more efficient.

switch

After this opcode, there must be a table of 16-bit words formed with the respective number of .disp directives, which denote jump displacements for switch values 0, 1, 2, etc. Number of .disp directives must not be less than maximum switch value expected. No bound checks are currently performed at run time (for the sake of effectiveness), so use of this opcode may be tricky! Used for switchfast C statement implementation.

jump.c <label>

Unconditional branch to instruction that is within the -128..127 range relative to the instruction immediately following this one. If target <label>is not within the reach of this instruction, assemble will try to use its 'long' counterpart, jump.s.

jumpz.c <label>

If R0 is zero, then branch to instruction that is within the -128..127 range relative to the instruction immediately following this one. If target <label> is not within the reach of this instruction, assemble will try to use its 'long' counterpart, jumpz.s.

jumpnz.c <label>

If R0 is not zero, then branch to instruction that is within the -128..127 range relative to the instruction immediately following this one. If target <label> is not within the reach of this instruction, assemble will try to use its 'long' counterpart, jumpnz.s.

jump.s <label>

Unconditional branch to instruction that is within the -32768..32767 range relative to the instruction immediately following this one.

jumpz.s <label>

If R0 is zero, then branch to instruction that is within the -32768..32767 range relative to the instruction immediately following this one.

jumpnz.s <label>

If R0 is not zero, then branch to instruction that is within the -32768..32767
range relative to the instruction immediately following this one.

calln.s <label>

Push address of the instruction immediately following call itself on stack, then jump to the instruction that is within the -32768..32767 range from the immediately following one.

calli

Indirect call: push address of the instruction immediately following call itself on stack, then jump to the instruction whose address is currently within R1.

callx.b <index>

Call extension functions represented with its index within the table of extension functions.

calls12.w <index>

Call the CyOS function which takes 0, 1, or 2 arguments. For 1-argument system functions, simply evaluate (just before call) the necessary expression so that the evaluation result is in R0, then use calls12.w. For 2-argument functions, evaluate the second argument, use move, then evaluate the first argument, then use calls12.w (or, if R1 is likely to be lost in the process of evaluation of the first argument, evaluate second argument, use push, evaluate first argument, use pop, then use calls12.w).

calls3.w <index>

Calls CyOS function which takes 3 or more arguments. This opcode first pops 3-rd off the stack, then acts exactly as calls12.w. So you must first evaluate and push arguments 3 and beyond in reverse order, then evaluate arguments 2 and 1, as shown above, then use calls3.w.

calld12.w <index>

Calls function located within CyOS dynamic library or even application that exports [some of] its functions. Very similar to calls12.w and even uses the same calling convention. However, it differs in that is must be immediately followed by the .disp directive which should define offset to a 4-byte static variable that holds address of export table of respective dynamic library. It is that table that is indexed with argument <index>.

calld3.w <index>

Just like calld12.w, calls function located within CyOS dynamic library or even application that exports [some of] its functions. Very similar to calls12.w (uses the same calling convention) and to calld12.w (requires .disp directive); see these opcodes for details.

retf

"Return far" — return from vm_exec().

retn

"Return near" — return from function called via calln.s.

retn.c <num>

Same as retn, but pop arguments off the stack upon return (here, <num> is number to be added to stack pointer just before return).

stack.c <num>

Add -128..127 to stack pointer.

push

Push R0.

pop

Pop R1.

popadd

The same as consequitive execution of pop and add operations. New in virtual machine version 11 (included in SysPack 55).

move

Move R0 to R1; same as "push pop" sequence, but by far more efficient. The "push pop" sequence, however, may also be more convenient sometimes, since it allows you to preserve R1. See calls12.w opcode description.

load0

Load 0 (zero) into R0.

load1

Load 1 (one) into R0.

load.c <num>

Load -128..127 into R0.

load.s <num>

Load -32768..32767 into R0.

load.l <num>

Load double word into R0.

loadic.b <num>

As same as loadic, but the parameter of this operation will be added to the byte pointer before execution. New in virtual machine version 11 (included in SysPack 55).

loadis.b <num>

As same as loadic, but the parameter of this operation will be added to the word pointer before execution. New in virtual machine version 11 (included in SysPack 55).

loadil.b <num>

As same as loadic, but the parameter of this operation will be added to the double word pointer before execution. New in virtual machine version 11 (included in SysPack 55).

leal.b <offset> <displacement>

Load effective address of 'auto' variable into R0.

leat.b <offset> <displacement>

Load effective address of 'object' variable into R0. If byte-sized offset specified in the instruction is 0, then such instruction actually means 'load this into R0'. Compilers for C++ and other OO languages may make use of this feature.

leag.u <label> <displacement>

Load effective address of 'static' variable or function into R0. If effective address is before, assemble will try to use its 'back' counterpart, leagb.u.

loadic

Load char pointed to by contents of R0 into R0.

loadis

Load short pointed to by contents of R0 into R0.

loadil

Load long pointed to by contents of R0 into R0.

storeic

Store char contained in R0 at the address pointed to by contents of R1.

storeis

Store short contained in R0 at the address pointed to by contents of R1.

storeil

Store long contained in R0 at the address pointed to by contents of R1.

loadlc.b <offset> <displacement>

Load char located at the address 'stack pointer' + 'next byte', into R0.

loadls.b <offset> <displacement>

Load short located at the address 'stack pointer' + 'next byte', into R0.

loadll.b <offset> <displacement>

Load long located at the address 'stack pointer' + 'next byte', into R0.

loadtc.b <offset> <displacement>

Load char located at the address 'this' + 'next byte', into R0.

loadts.b <offset> <displacement>

Load short located at the address 'this' + 'next byte', into R0.

loadtl.b <offset> <displacement>

storelc.b <offset> <displacement>

Store char from R0 at the address 'stack pointer' + 'next byte'.

storels.b <offset> <displacement>

Store short from R0 at the address 'stack pointer' + 'next byte'.

storell.b <offset> <displacement>

Store long from R0 at the address 'stack pointer' + 'next byte'.

storetc.b <offset> <displacement>

Store char from R0 at the address 'this' + 'next byte'.

storets.b <offset> <displacement>

Store short from R0 at the address 'this' + 'next byte'.

storetl.b <offset> <displacement>

Store long from R0 at the address 'this' + 'next byte'.

loadgc.u <label> <displacement>

Combines leag.u and loadic

loadgs.u <label> <displacement>

Combines leag.u and loadis

loadgl.u <label> <displacement>

Combines leag.u and loadil

load0p

Combines load0 and push.

load1p

Combines load1 and push.

loadp.c

Combines load.c and push.

loadp.s

Combines load.s and push.

loadp.l

Combines load.l and push.

lealp.b

Combines leal.b and push.

leatp.b

Combines leat.b and push.

leagp.s

Combines leag.u and push.

loadicp

Combines loadic and push.

loadisp

Combines loadis and push.

loadilp

Combines loadil and push.

loadlcp.b

Combines loadlc.b and push.

loadlsp.b

Combines loadls.b and push.

loadllp.b

Combines loadll.b and push.

loadtcp.b

Combines loadtc.b and push.

oadtsp.b

Combines loadts.b and push.

loadtlp.b

Combines loadtl.b and push.

loadgcp.s

Combines loadgc.u and push.

loadgsp.s

Combines loadgs.u and push.

loadglp.s

Combines loadgl.u and push.

load0m

Combines load0 and move.

load1m

Combines load1 and move.

loadm.c

Combines load.c and move.

loadm.s

Combines load.s and move.

loadm.l

Combines load.l and move.

lealm.b

Combines leal.b and move.

leatm.b

Combines leat.b and move.

leagm.s

Combines leag.u and move.

loadicm

Combines loadic and move.

loadism

Combines loadis and move.

loadilm

Combines loadil and move.

loadlcm.b

Combines loadlc.b and move.

loadlsm.b

Combines loadls.b and move.

oadllm.b

Combines loadll.b and move.

loadtcm.b

Combines loadtc.b and move.

loadtsm.b

Combines loadts.b and move.

loadtlm.b

Combines loadtl.b and move.

loadgcm.s

Combines loadgc.u and move.

loadgsm.s

Combines loadgs.u and move.

loadglm.s

Combines loadgl.u and move.

inc1

Add 1 to R0.

inc2

Add 2 to R0.

inc4

Add 4 to R0.

incic1

Add to byte addressed by eR0 register. New in virtual machine version 11 (included in SysPack 55).

incis1

Add to word addressed by eR0 register. New in virtual machine version 11 (included in SysPack 55).

incil1

Add to double word addressed by eR0 register. New in virtual machine version 11 (included in SysPack 55).

dec1

Subtract 1 from R0.

dec2

Subtract 2 from R0.

dec4

Subtract 4 from R0.

decic1

Subtruct 1 from byte addressed by eR0 register. New in virtual machine version 11 (included in SysPack 55).

decis1

Subtruct 1 from word addressed by eR0 register. New in virtual machine version 11 (included in SysPack 55).

decil1

Subtract 1 from double word addressed by eR0 register. New in virtual machine version 11 (included in SysPack 55).

patch

Some words after this opcode are a list of patches. A zero word (.word 0) is a marker of the end of the list. Every word is a relative offset of a label (.disp). Every label is a label of ".ldisp" (address of variable). To each value of .ldisp the absolute address following it byte will be added. New in virtual machine version 11 (included in SysPack 55).

lshift1

Arithmetically shift R0 left by 1 bit.

lshift2

Arithmetically shift R0 left by 2 bits.

rshift1

Arithmetically shift R0 right by 1 bit.

rshift2

Arithmetically shift R0 right by 2 bits.

add

Add R1 to R0, result in R0.

add.c <num>

Add -128..127 to R0, result in R0.

add.s <num>

Add -32768..32767 to R0, result in R0.

add.l <num>

Add double word to R0, result in R0.

sub

Subtract R0 from R1 (!), result in R0.

neg

Negate R0.

mul

Multiply R0 by R1, result in R0.

mul.c

Multiply eR0 by parameter of this command. New in virtual machine version 11 (included in SysPack 55).

muladd.c

As same as consequtive execution of "mul.c" and "add" commands. New in virtual machine version 13 (included in SysPack 56).

jumple.c

Jump, if eR0 <= eR1. In that case eR0 = 0 after execution, otherwise eR0 = 1. New in virtual machine version 13 (included in SysPack 56).

jumpge.c

Jump, if eR0 >= eR1. In that case eR0 = 0 after execution, otherwise eR0 = 1. New in virtual machine version 13 (included in SysPack 56).

div

Divide R1 by R0 (!), result in R0.

mod

Divide R1 by R0 (!), remainder (result) in R0.

and

Bitwise AND of R0 and R1, result in R0.

or

Bitwise OR of R0 and R1, result in R0.

xor

Bitwise eXclusive OR of R0 and R1, result in R0.

Recent Additions.

Syspack V. | Bytecode V. | Own version in root.inf | Changes
53, 54 | 10 | N\A | initial implementation
55 | 11 | N\A | decic1, incic1, decis1, incis1, decil1, incil1, popadd, patch, loadic.b, loadis.b, loadil.b, mul.c
56 | 13 | N\A | muladd.c, jumple.c, jumpge.c, leagb.u
57 | 14 | 1.3.3 | "root.inf" added
N\A | 15 | 1.4.4 | lshift, rshift, urshift1, urshift2, urshift, native, bcopy.b, swap, push2, pop2, move2, nop
N\A | 16 | 1.5.1 | loadiuc, loadius, loadiuc.b, loadius.b, loadluc.b, loadlus.b, loadtuc.b, loadtus.b, loadguc.u, loadgus.u, cuwd, cubd, deciuc1, inciuc1, decius1, incius1, setb, setbe, seta, setae, mulu.c, mulu, divu, modu

What Will Come Next

Since we assumed nothing, we'll profile anything :-) and come up with the rest of 256-147=109 opcodes. Most probably, there will appear direct loads/saves for static variables and better (read: some :-) support for increments and decrements for variables (as opposed to memory locations denoted with address expressions).

Assembler should become macro assembler (not a top priority task, though).

Life should become easier :-).


Utilities

Table of Contents
  • 2music
  • 2mus
  • mus2txt
  • t2mf
  • 2pic
  • filer
  • pack list

2music
(Professional Edition only)

This program is designed for converting MIDI files to MUSIC files of a Cybiko computer. It is the most recent successor of 2mus.exe, with advanced algorithms and extra functionality.

USAGE: Midi_Music_Converter <input_file>.mid <input_file>.music [/v=] [/t=] [/a=] [/i= /i= /i= ...] [/strict]
OR Midi_Music_Converter <input_file>.mid \info=[full | brief]
/v=
method of conversation (1 or 2):
1 - the highest note is chosen from two simultaneously played notes.
2 - the latest pressed note is chosen from two simultaneously played notes.

/t=
transposition (note shift)(-127 ... +127) in semitones.

/a=
turn autotransposition on (a=1) or turn off (a=0).
When autotransposition is on playing notes out of Cybiko computer sound range is prevented.

/i=
instrument numbers to be converted (i < 256). If not selected all instruments will be converted.

/strict=
if this option is turned on, MIDI files with errors are not converted and warning messages are displayed. if this option is turned off, all MIDI files with are converted, but there is slight possibility of incorrect conversion.

/info=
run in full (info=full) or brief (info=brief) info mode to obtain track comments
Default settings: /v=1 /t=0 /a=1. If no tracks are selected? all tracks are to be converted.

Examples:
Midi_Music_Converter chimes.mid chimes.music /v=1 /t=10 /a=1 /i=1 /i=2 /i=14
Midi_Music_Converter chimes.mid /info=full /strict

2mus

The Cybiko SDK lets you work with sound effects and musical fragments, either stored in an application or in a file in internal sound format (*.mus). This utility converts from standard MIDI format to CYBIKO's internal sound effects format.

USAGE: 2mus<input_file>.mid
<input_file>.mid
standart MIDI sequence file.
This utility creates <input_file>.mus which can be added to the application resources by filer utility.

mus2txt

This utility converts CYBIKO internal sound effects format to MIDI sequence text format.

USAGE: mus2txt<infile>.mus <outfile>.txt
<infile>.mus
internal CYBIKO format of sound effects.

<outfile>.txt
text MIDI sequence Type 0 format.
You can use the freeware t2mf filter to convert <output>.txt to MIDI Type 0 file. For full description of this format see t2mf.

t2mf

This freeware utility converts MIDI sequence text files to standard MIDI sequence Type 0 files.

USAGE: t2mf<<input>.txt><output>.mid

<input>.txt
text MIDI sequence Type 0 format.

<output>.mid
standard MIDI sequence file.
See also mus2txt.

2pic

Cybiko SDK lets you work with lists of pictures, which can be composed from standard graphics files (currently only *.bmp, *.dib , *.fli, *.flc and *.cel formats are supported). All CYBIKO picture lists can contain from 1 to 255 pictures. Maximum resolution of each picture is 255 by 255 pixels with 4-bit color (WHITE, LIGHT GRAY, DARK GRAY, BLACK). One color can be marked as transparent color.

USAGE: 2pic[<mode>] <ofile>[.pic]<ifile>.{bmp|dib|fli|flc|cel}[<ifile> [...]]

<ofile>[.pic]
CYBIKO picture list file.

<ifile>.{bmp|dib|fli|flc|cel
standard graphics files.

<mode>
0 - 2-bit bitmap, use WHITE as transparent color.
1 - 2-bit bitmap, use LIGHT GRAY as transparent color.
2 - 2-bit bitmap, use DARK GRAY as transparent color.
3 - 2-bit bitmap, use BLACK as transparent color.
-f - 1-bit font, treat WHITE as transparent and BLACK as opaque.
-p - 1-bit font, treat both WHITE and BLACK as opaque.
<ofile>[.pic] can be added to the application resources by filer utility.

filer

This is the CYBIKO compressor and archive utility. Files added to application resources (such as music, graphics or arbitrary data) can be used from the application using filename or resource ID.
To decrease the size of the application, files can be compressed by filer.

USAGE: filer<command> <archive> [[<prefix>]<file1> [...]]]

<command> is one of the following:
a - add files (create archive).
p - paranoid (same as above but unpacks and compares files afterwards).
e - extract files (unpack archive).
l - list files (display contents of archive).
[[<prefix>]<file1> [...]]] is list of the files.

<prefix> (more than one prefix allowed, in any order):
@ - this file is actually a list (read and process its contents). See packlist.
+ - compress this file (even if '-' applied to the list).
- - do not compress this file (even if '+' applied to the list).
* - do not store file name (will be accessible by index only).
? - do not store file extension (but store name).
# - ignore file (this character starts comments in list files).

pack list

This utility creates a pack list file, which can be used as input to filer.

USAGE: packlist<listfile> <filename1> [ <filename2> [ ... ]]

<listfile>
<filename1> [ <filename2> [ ... ]]

<filename1> [ <filename2> [ ... ]]
list of the files.


Cybiko Console

Standard Application Resources

Table of Contents
  • About Standard Application Resources
  • Root.inf file
  • Root.ico file
  • Root spl file
  • Intro.pic file
  • Score.inf file
About Standard Application Resources
If you would like to make your application an integral part of Cybiko computer's software (i.e. make it so called "good citizen"), you have to prepare some special files and make them available to the archive utility (e.g. by putting them into the RES subfolder of your project). When the device boots up, special service tasks of a system pack read out the given information to the user in a convenient, graphic display.

Root.inf file
Within this file, each line has special meaning: thus, every line has a special format. Strings couldn't be omitted or placed in other order. The purpose of these lines is described in the table, below:

Line Number | Meaning
1 | This line describes a type of your program and may have only one of the next three abbreviations – app, game, lib. In other words, this line defines a part of Cybiko computer's Main Desktop, where your program will be placed.
2 | The full name of your program. It will be displayed to user.
3 | This line is reserved and has to be EMPTY.
4 | This line is reserved and has to be EMPTY.
5 | A list of files (separated with spaces) that have to be distributed as a part of your program. If Cybiko computer can’t find any of these files, the application won't be launched. If you would like to remove your program, files from this list will be removed. If your program consists only one file, this line has to be empty.
6 | A list of masks of files (separated with spaces) your program can create. For example, *.txt – for text editor or *.sav for game. Masks have to be delimited with spaces. These files will be shown by CyberLoad.
7 | A unique identificator of your program. This identificator is a name of the main process created by your program. It can be a number less than 65535 with leading "#" sign or a string. String could not include "#" character. For example, “Billiards” or "#57".
8 | Version number of your program in format "Digit.Digit.Digit". For example, "1.2.3". This version number have to be the same as in root.spl.
9 | Min number of CyOS, which is needed for correct work of your program. An application can't be launched if you use a version of CyOS older then written in this line. Format of this line is the same as format of the 8th line.
10 | Any information written by authors of the application or game.
11 | A list of required libraries; their minimal versions immediately follow in angle brackets(delimeted with spaces). For example, bytecode.dl <1.1.1> cybank.dl <1.2.2>. If any library is absent or it's version is older than written in this line, application will not be loaded and diagnostic message will be displayed.
12 | If your program needs some external devices, IDs of these devices have to be places in this line. 2 is an ID of MP3 cartridge and 3 is an ID of Memory Expansion cartridge. If you don't have any device written in this line the application will not be launched.

Root.ico file
This file is a placeholder for your program's Icon. The size of this icon has to be 48 x 47 pixels.

Root.spl file
Information given below must be included in this file:
  • the rules of your game or the purpose of your program;
  • a description of control keys;
  • a version number (for example, "Version 1.3.7");
  • your copyright (for example, "Copyright © Cybiko Inc., 2000.").
Intro.pic file
This file is a placeholder for the full screen picture which is viewed each time the application is launched from within the Cybiko computer's main desktop. The size of this picture has to be 160x100 pixels.

Score.inf file
This file is used for storing of the best results of game in the application archive. It must NOT be compressed. Please, see respective tutorial for further details.


Cybiko Console

Table of Contents
  • About Cybiko Console
  • How to Get Your Application to Your Cybiko computer
  • COM port
  • Console commands

About Cybiko Console
Cybiko console was developer as a way for you, the user, to send third-party applications to your Cybiko computer. Cybiko console can also be used to view various other information about your Cybiko computer.

How to Get Your Application to Your Cybiko computer
  1. Connect your Cybiko computer, using the special connection cable that came with it, to a COM Port. (If you don't know what a COM Port is, look below).
  2. Start the Cybiko console application.
  3. In the Port menu, choose COM port to which you have connected your Cybiko (usually COM1).
  4. To send an application to your Cybiko computer, choose File->"Send File(s)" submenu, or press <Ctrl><S>. The Send File dialog will appear.
  5. Choose the file name of your application (<app_name>.app) and press <Enter>. The process of sending the application to your Cybiko has now begun.
  6. That's is! You can now use the application like you would any other.

COM Port
A COM port is actually called a serial port. It's very small and has 9 slots where pins go in. If you don't have one, you may need an adapter to make your USB port into a serial port.

Console commands
There are some commands for Cybiko computer control through the console:
  1. ls command
  2. rm command
  3. cp command
  4. sformat command
  5. fdoctor command
  6. boot command
  7. ver command
  8. sysinfo command
  9. os_kind command
  10. cfg command
  11. id command
    12.
ls command
Outputs a list of files. You can use arguments and options of this command in any order. Option "-l" outputs the list of file names with length of each file, followed by information about total number of files and by information about main flash card. Additionally, it's possible to use "-t" option ("times") to output the times of the last changes of files, this option used with "-l" option only. This command, as well as other file commands, can be used with unlimited number of arguments such as as file names or masks for files with metasymbols '*' and '?' in unix-style. Option "/*" may be used in conjunction with "-l" option to get information about file devices and their types. Without "/*" option file list will be followed by information about main flash card, irrespective of the information on files from which the device was outputted.

Usage: ls { -/* | -l | -t }
 -/* — information about file devices and their types (used with "-l" option)
-l — list of file names with the length of each file
-t — the time of the last change in a file(s) (used with "-l" option)

rm command

Remove file (or files). The option '-f ' ('f' stands for 'force') can be used to remove multiple files that are specified via a file mask (a.k.a. wildcard) without ever asking you whether or not you wish to remove a particular file. The newly added option -p reports on the execution progress once per second. The executable file implementing this command resides in System.a archive.

Usage: rm { -f | -p } remove_file
-f — remove without confirmation
-p — reports the execution progress once per second

cp command

This command copies one file (the 1st argument) to another one (the 2nd argument). If the last argument is written down as '/device_name/', this command copies files listed or found on masks of the previous arguments on this device, with preservation of names of files. The command is convenient for the recording of small files on external devices, because the console could not do this directly yet. The option “-v” as a first argument makes this command a little more talkative (informs about success or unsuccess of the each copying). The option "-f" relieves from questions about overwriting of files. The option-p, while copying a file, every second writes a percentage of this execution. All options of a command cp should be put right after it up to a name of files.

Usage: cp { -m | -f | -v | -p } source_file destination_file
cp { -m | -f | -v | -p } source_file(s) destination_directory
-f — overwrite without confirmation
-v — verbose
-m — move or rename file(s) without real copying
-p — feedback (percentage of completion)

sformat [device_name] command

This command formats a device. The only argument is a device name without a slash. If the device_name is blank, the main flash card will be formatted. The “format” command does the same, except it not only formats occupied blocks, it formats the occupied blocks.

fdoctor command

This command checks the file system integrity in main flash card. “-I” option allows performing a test without attempts to repair found mistakes. It’s not recommended to run this command if you have a little amount of memory (RAM).

Usage: fdoctor { -I }
-I — test without repair mistakes

boot command

The only option – the name of boot file. This command makes this file bootable.

ver command

Outputs OS version number and time when OS was built

sysinfo command

Outputs information about the main flash card or other devices with option /device_name, this will output information about other devices

os_kind

This command outputs a kind of CyOS (release/debug/update)

cfg command

Configures the system. If this command is used without options, it outputs current settings. With option “?”, this command outputs a configuration manual. The Configuration manual is given below.

usage: cfg

dumps current system settings

***

usage: cfg load|save|dump [file_name]

load - load config from default or specified file

save - save config to default or specified file

dump - dumps config from default or specified file

***

usage: cfg sound [on | off]

disables enables any sound

on - turn sound on

off - turn sound off

if on | off are omitted - turns sound on

***

usage: cfg keysound [normal | short | off]

handles only keyboard sound behavior

normal - turn keyboard click sound normal

short - turn click to short beep

off - turn keyboard sounds off

if parameters are omitted - turns keysound normal

***

usage: cfg comm [on | off]

disables/enables communications

on - communications on

off - communications off

if on | off are omitted - turns communications on

***

usage: cfg channel <number>

set rf channel number

***

usage: cfg keyboard <layout_name>

set keyboard layout

***

usage: cfg hardware <dword_hardware_version>

set hardware version (double word)

id command

This command outputs the CyID of Cybiko computer.


Change Log

2.1.8 08/02/2001 3:19 PM

[vcc1] C compiler now handles the 'unsigned' type qualifier, so it is now possible to use 'unsigned char', 'unsigned int' etc. types.

IMPORTANT NOTICE: if you're using 'unsigned' in the 'bytecode' (vs. 'native') compilation mode, you have to upload the newest bytecode.dl (found in the 'lib' folder) to your Cybiko computer, otherwise your program will not start. The thing is that currently there is no syspack with 'bytecode.dl' supporting 'unsigned' opcodes. If however you compile your program with '-n' switch, you don't have to bother yourself with that.

[tools] Several new or improved utilities: Media Converter, 2music, etc. The latter introduces new, advanced algorithm for handling multi-track MIDI scores; it is to be shipped with SDK Pro only.

[vcc1] Many important internal improvements and bug fixes in the compiler. In particular, many annoying problems with explicit type casts had been fixed (in the course of the 'unsigned' type qualifier implementation). Please note however that the new compiler is somewhat less forgiving in that it tries to strictly follow ANSI C specification -- as a result, some pieces of invalid source code that used to "work" will most probably fail.

[media] 519 new bitmaps in the collection of the royalty-free media files. With this addition, total number of bitmaps reaches 4174. It is to be shipped with SDK Pro only.

[vcc] -V option doesn't check the maximum version limit anymore

2.0.7 04/27/2001 18:12

[vas] no more extra checks in 'skip'

[vcc1] implemented '-W' and '-w' options

[vcc1] 'return' without expression is now illegal in a non-void function

[vcc1] subsequent type casts (e.g. '(int)(int)123') handled improperly

[vlink] diagnostics quality has been improved significantly

[vcc1] local structures' and arrays' initializers did not work

[vcc] occasional crash in the middle of compilation has been fixed

[vcc1] introduced new 'unsigned shift' operators '>>>' and '>>>=')

[vcc1] 'enum' did not work correctly under some circumstances

[vcc1] better handling of scope rules

[vcc] bytecode.dl requirement has been removed from the automatically generated root.infs

[vcc, vlink] implemented -g and -G options

[vcc1, vas] implemented -g option

[sdk] bitmaps, MIDI scores and other resources are now part of the SDK distribution

[vcc, vcc1, vas, vlink] implemented -n switch (native code generation mode)

1.2.21 03/26/2001 17:52

[docs] miscellaneous improvements in the documentation

[2mus] fixed command line parsing

[inc] Mutex_dtor(), Flag_dtor() and Flagex_dtor() have been fixed

[vcc1] implemented shifts by variable number of bits

[vcc1] fixed multiplication / division / modulo with long operands

[vcc1] size of a structure is even if it contains even a single field that needs alignment (for better compatibility with Cygnus compilers)

[vcc1] function pointers could be 'typedef'-ed (i.e. it is now possible to introduce a type 'pointer to function returning...')

[vas, vlink] line number info is included in object files (though not used yet)

[vcc1] introduced extended format for the '__dl' function type modifier

[vcc1] '__inline' is now a synonym of 'inline' (and the latter is deprecated)

[vcc1] 'inline' function type modifier has been fixed

[vcc] fixed bug with empty default object file extension in compile-only mode

[vcpp] the -E option is now described in online help

[tutorials] added dynamic linkage tutorials, dl_app and dl_lib

1.1.15 03/01/2001 18:35

[vcpp] fixed bug that caused lockup under Windows 9x and some minor issues under Windows NT/2000 when including headers from an include search list specified with -I option

[vcc] -R option added to manage automatic root.inf generation

[vlink] added support for dynamic libraries

[vas] added .dl <label> <ordinal> directive that allows to export functions from dynamic libraries

[vcc1] functions pointer acceptable

1.1.10 02/14/2001 19:15

[vcc1] fixed bug that prevented prototypes of functions returning structures or references to work properly

[vcc] fixed -S option

[vcc1] structures are considered lvalues so that an element of an array of structures can be used at the left side of assignment

[vcc1] even small structures are returned by reference

1.1.9 02/05/2001 17:38

[vas\vcc1] new option -Vsp54 to build big application for syspack 54

[bytecode.dl\vas] new opcode "leagb.u"

[vcpp] preprocessor exits when stumbles upon unrecognized option (used to just issue a warning)

[vcpp] if given either of -M options, preprocessor turns itself into dependencies generator -- it outputs dependency records for the specified C/C++ source file rather then its preprocessed contents; even in this mode, it recognizes and processes other switches, e.g. -D, -I, etc.

1.1.8 01/25/2001 15:26

[vcc1] type check for arguments and return values is improved

[vcc1] large structures assignment is implemented

1.1.7 01/19/2001 19:16

[vcc1] redundant code removal for expressions is implemented

[vcc] -A option allows to specify a library search path; if not specified, defaults to $(CYBIKO_SDK)/lib

[vlink] -A option allows to specify a library search path, so that object files not found in current directory are searched there; only one path can be specified

[vlink] running vlink without parameters displays help

[vcc1] large structures can be passed and returned by value

[vcc1] error messages are now in Microsoft format (Windows version only)

[vcc1] new option '-ws'

[vcc1] bug with deref lvalue fixed (Ex: "char **p; main() { *p = 34; }")

[vcc1] implemented keyword 'inline'; inlining is restricted and does not apply under some circumstances (that is, some inline functions would be treated as regular)

[vcc] bug is fixed that prevented temporary files from being removed if compilation wasn't successful

[API] added simple serial port interface

[vcc1] final comma available in enum declaration

[vcc1, vas, vcc] new option '-V<ver> 'for bytecode.dl compatibility<![endif]>

1.1.1 01/30/2001 23:37

[vcc] specifying `.o' extension for output file automatically enables compile-only mode

[vas] stack.c stack.c collapsed

[vas] new parameter <type> for pipe_push_into()

[vas] add_patch() generates emit_????() now

[vas] all optimizations moved to pipe_push_into()

[vcc1] try to generate setz instead setnz

[vas] new opcodes jumple(gt).c <- setgt(lt) jumpz.c

[vas] new opcode muladd.c <- mul.c add

[vcc] temporary files are stored in system temp directory, not in `/tmp' as it used to be

[vcc] smarter SDK home directory detection algorithm

[vcpp] added support for backslashes in both source and include filenames

1.0.19 10/23/2000 17:00

[vas] new opcodes: add.c(s) -> inci?.b

[vas] new optimize algorithm (pipe)

[vlink] new tool for separate compilation

[vcc1] adjusted to support separate compilation. Introduces new assembler directives. Incompatible with previous versions as a result

[vas] adjusted to support separate compilation. Produces object files instead of binaries

[vas] statistic moved to dump procedure

[vcc1] bug with enum type fixed

[vas] new opcode: mul.c

[vas] new opcode: patch

[vas] new opcode: popadd <- pop add

[vcc1\vas] new opcodes: inci?1 && deci?1

[vcc1] fixed bug with / 2(4)

[vas] new version used flex and bizon

[vcc1] fixed bug with char omitted size array initialization

[vcc1] fixed bug with array with size != 1, 2, 4

[vas\bytecode.dl] .disp is unsigned now

[vas] profiler for frequency pair opcodes (-p<num> option)

[vmake] fixed bug with not existing “rm –f tmp\*”

[vas\vasx] increase module size up to 128K; increase max label up to 32K

1.0.18 10/11/2000 17:00

[vmake] –p<0|1|2> option added

1.0.17 08/23/2000 00:30

[bytecode.dl] available to set and reset m_quit flag from the program

[vcc1] available to scan hex and octal constants as unsigned long

[vcc1] optimization: !a && !b -> !(a || b)

[vcc1] recognize expressions that would use single register (such as addition or subtraction of a constant) and generate 'move' rather than 'push/pop' to preserve result of previous expression (?)

[vcc1] compiler check arguments' and return value's types

[vcc1] omit unnecessary '.ln' directives at not typed nodes

[vcc1/vas/bytecode.dl] new command "patch.u" (for patching)

[vas] new directive ".ldisp

1.0.16 08/19/2000 22:50

[vcc1] static objects are now output in the order that allows for more compact in-memory layout (i.e. bigger modules could be generated)

[vas] added extra diagnostics: longest forward and backward patches

[vcc] first public release of compiler's driver

[vcc1] the main() proc (application entry point), as well as any other exported function, could now be given up to 3 arguments, of any type (passed as 'long's)

[vcc1] fixing fetching address of array element on the right side of 'arrow' operator

[vcc1] 'static' qualifier works with variables declared within blocks; it is also possible to specify initializers for such variables

[vcc1] max number of elements per array's dimension enlarged up to 64000

[vcc1] keyword 'extern' now works not only with functions but also with variables; i.e. forward declaration of variables is also possible

[vcc1] if compilator's compilation's return code is not 0 (i.e. if compile-time errors were detected), output (usually .bin) file will be removed

[vcc1] unions are now fully implemented

[vcc1] now if we try to assign a number to a variable and the number is not within the range for respective type, we'll get a warning

[vcc1] duplicate case labels in 'switchfast' statements now get rejected

1.0.15 07/30/2000 00:04

[vcc1] unions implemented.

[vcc1] 'static' qualifier has effect within functions' bodies.

[vas/bytecode.dl] implemented 40 new opcodes, which are combinations of 'old' opcodes with subsequent 'push' or 'move'; assembler touch to replace these sequences (in fact, pairs) with single opcode

[vcc1] new opcodes used to emit some types of relocation records

[vas] implemented 'dead code' elimination (excludes all opcodes after 'ret', 'jump.c' etc up to the next .label); this covers some rare cases not yet handled by the compiler, e.g. 'break' at the very end of 'switch'

[vcc1] fixed optimizer's handling of [ ]; that used to be treated as [ ]

[vcc1] fixed '<' '>' '<=' and '>=' operators applied to pointers

1.0.14 07/09/2000 06:16

[vcc1] while generating code for the 'struct_pointer->struct_field' construct, compiler emits single opcode
add.c
rather than
move
load.c
add

[bytecode.dl/vas] implemented six new opcodes:
loadgc.s loadgs.s loadgl.s storegc.s storegs.s storegl.s

[vcc1] compiler tought to use the above mentioned opcodes in place of 'leag/loadi' and 'leag/storei' pairs; also, 'leag/move/load.c/storei' sequences now look like 'load.c/storeg' etc.

[vcc1] 'cbd/cwd' opcodes are no longer generated after imported/system functions whose result isn't actually used

[vcc1] addition/subtraction opcodes are no longer generated after post-decrements and post-decrements, respectively, if results of the latter are actually unused, as in for() loops

[vcc1] compiler outputs relocation records as:
leag.s
storegl.s
rather than (much longer)
leag.s
move
leag.s
storeil

[vas] implemented counter for the most frequent opcode pairs

1.0.13 07/06/2000 11:48

[bytecode.dl] ATTENTION! bytecode.dl 1.0.13 is INCOMPATIBLE with old bytecode modules; from now on, backward compatibility will be maintained for every release, but right now you have to download new bytecode.dl AND re-compile your applications with vcc1/vas 1.0.13

[vas] implemented 'cbd' (stands for 'Convert Byte to Double word') opcode

[vcc1] the above mentioned 'cbd' opcode now gets emitted right after system functions that return bytes (in fact, 'bool', since for 'char' functions gcc actually returns 'int')

[bytecode.dl] added version number; bytecode loader now ensures that its own version is not less than that of the module being loaded

[bytecode.dl] added room for the table of functions exported by bytecode modules; though functions that are not methods (of exported structures) could not be exported yet

1.0.12 06/25/2000 21:05

[vcc1] ++foo.bar, ++baz->bar etc did not work since results of '.' and '->' were not recognized as lvalues

1.0.11 06/13/2000 07:04

[bytecode.dl] common library cache size extended (up to 80 entries) to fit cylandia's grown demands

1.0.10 06/05/2000 00:04

[vcc1] option -d (dump code tree) caused GPF on some files

1.0.9 06/04/2000 00:11

[vas/vcc1] implemented new 'cwd' opcode (see cybiko_pcode.htm for details); with this opcode, fixed problems with results of CyOS functions that return 'char' or 'int', such as rand()

1.0.8 06/03/2000 03:44

[vcc1] compiler does not emit '.even' directives for static data bigger than 1 byte that actually do not need alignment; this makes code shorter a bit; quite important for programs (such as Cylandia) that use 'video sequence compiler' vseq.tsh, which generates a lot of 3-byte so called 'sequence loops' that reside in 'static' memory

[vcc1] compiler did not reject prototypes of gcc-compiled vararg functions with no named arguments (ANSI C requires at least one)

[vcc1] gcc-compiled (i.e. 'import' or '__cyos') vararg functions with more than one named argument used to be called incorrectly: all arguments used to be pushed on stack, while all named arguments but the very last one (up to 3) should have been passed in registers; for that reason, sprintf() and some other CyOS functions did not work

[t2mf] PD t2mf utility by Piet van Oostrum has been ported to Win32 and included into the distributive of SDK so that the output of our mus2txt utility could be converted back to .mid (MIDI Type 0) format

1.0.7 06/01/2000 03:29

[bytecode.dl/main.e] bytecode bootstrap module is re-built based on the cWinApp class, so it is now possible to use more of the CyWin API; as a drawback, .bss segment of the module became larger: 308 bytes vs. 256 (see [old] table below), and entire module now takes 404 bytes (vs. 352)

[vcc1] structure fields that need to be aligned are now aligned correctly; alignment rules match those of the GNU C compiler except for some dword-sized fields that GNU C (unnecessary) aligns on a 4-byte boundary when 2-byte would do; for example, if we define 'c' as 'struct { char a; long b; } c;' then 'sizeof c' would be 6 for vcc1 and 8 for GNU C; if some application requires strict binary structure compatibility with GNU C, then it should define 'c' like this: 'struct { char a, STUB; long b; } c;'

[vcc1] compiler now supports initialized static 'char' arrays with omitted size, i.e. such constructs as 'char foo[] = "Foo";'

[vcc1] initialized static data buffers were not freed (i.e. there were small memory leaks within compiler itself)

[vcc1] compiler now supports relocation records; most important is that now it is possible to initialize static pointer with static object's address, like this:
static char* arr[ 3 ] = { "foo1", "bar", "baz" };
or even like this:
struct foo { void* x1; int x2[ 5 ][ 3 ]; } myfoo;
static void* ptr = & myfoo.x2[ 3 ][ 1 ];

1.0.6 05/30/2000 01:30

[vcc1/vas] there was no way to escape most special characters (e.g. quotes or newline) within character strings; compiler parsed all strings correctly, but failed to escape certain characters while passing them to assembler; as a remedy, compiler now passes strings byte by byte, it doesn't use assembler's '.string' directive anymore (for this purpose)

[vcc1] logical operators || and && produced 'zero/non-zero' rather than strictly correct 'zero/one' when used
- on the right side of assignments (=, +=, -=, etc.),
- within expressions used as functions' arguments,
- within expressions used as functions' return values

[vcc1/vas] implemented 'setz' and 'setnz' opcodes and used them
- to fix the problem with operators || and && (see above),
- to optimize code sequence generated for the ! (logical not) operator

[vcc1] implementation of access to dynamic libs had numerous flaws:
- static variables holding pointers were not always aligned properly,
- DynamicLibrary dtor was always given wrong 'this' pointer,
- init/cleanup of a library was triggered with just function prototype, not actual usage (i.e. rtl was attempting to load at startup, and free at exit, all libraries that vcc1 compiler saw in system headers)

[bytecode.dl/main.e] greatly reduced per-application overhead; the size of main.e (interpreter's bootstrap code that gets included into any application's .app archive) reduced from 1207 to 213 bytes; its memory map now looks like this:
code 52 bytes
idata 44 bytes
bss 256 bytes (this includes app's internal name, own timer, etc.)
----- ---------
total 352 bytes

[sdk] minor changes in SDK directory structure; sample makefiles updated to reflect these changes

1.0.5 05/29/2000 01:36

[vcc1] initialization expressions at the start of each block used to be computed in the reverse order; that was particularly evil if these expressions engaged function calls or referred to each other's values
[vcc1] compiler (erroneously) did not allow 'long' constants sometimes

[vcc1] compiler did not recognize a structure if it (structure) were the very last symbolic name defined in the module

[vcc1] namespaces' clashes resolved (did complete overhaul of pass1)

1.0.4 05/27/2000 13:41

[vas/vcc1] implemented new 'add.[c|s|l]' opcodes which are capable of adding arbitrary constants to R0; compiler tought to emit these opcodes

[vcc1] post-increment and post-decrement operators re-implemented with new 'add.?' opcodes, so that they handle pointers to any structures now

[vas/vcc1] implemented 'cmpe.[c|s|l]' opcodes which compare arbitrary constants with R0 and set the latter to 1 if R0 equals to the constants, or to 0 otherwise; compiler tought to emit these opcodes

[vas/vcc1] implemented "standard" 'switch' statement (that is: with optional 'default' label; doesn't break if switch expression is "out of range"; number of case labels not limited)

[vcc1] implemented 'switchfast' statement which acts exactly as old-style 'switch'; that is, no 'default' label, no negative cases, no comparisons: compiler generates jump table; the latter must not be "sparse": compiler ensures that at least 50% of jump addresses are used; if one of these conditions not met, compiler switches to "regular" 'switch'

[vcc1] processes (or, if more exactly, their queues) launched by modules made with vcc now get modules' names (sans extensions) at startup

[vas] implemented 'calld12.w' and 'calld3.w' opcodes; with these opcodes, in turn, implemented links to dynamic libraries; to call a function located within dynamic library (or even application) it is now necessary to just supply a prototype, like this: '__cyos "CyWin" 294 int imin(int,int);'

1.0.3 05/22/2000 12:33

[vcc1] both pre- and post-decrements of pointers produced incorrect results if the objects the pointers were pointing to were bigger than 128 bytes

[vas/vcc1] it is now possible to use arbitrary constants: compiler tought to emit and assembler tought to recognize 'load.l' opcode; bytecode.dl also modified to support new opcode

[vcc1] expressions ' % 2' and ' %= 2' are now handled even more effectively ('load1' is used instead of 'load.c 1')

1.0.2 05/16/2000 20:07

[cybiko_pcode.htm] numerous changes and *corrections*

[vcc1] main() is now always considered vararg, regardless of actual definition; compiler also no longer requires at least 2 arguments to main(); any number of arguments will do

[vas] implemented 'jump.s', 'jumpz.s', and 'jumpnz.s' opcodes that use 16-bit signed offsets; made available 'load0' and 'load1' opcodes that were implemented earlier but were never included into the scheduler's table (there were no room); all opcodes are now emitted as indices, not offsets within scheduler's table (i.e. not pre-scaled)

[vcc1] compiler tought to make use of new opcodes 'load0' and 'load1'; however, compiler still writes 'jump*.c' opcodes with effective range -128..127, and it is up to assembler to replace them with 'jump*.s' opcodes whenever necessary

[vcc1] typedefs did not work properly; most annoying, compiler did not recognize simple integer typedefs (as in 'typedef long clock_t') as integers thus effectively disabling almost any use in expressions

[vcc1] compiler did not handle complex return types (such as pointers to structures) correctly

1.0.1 05/04/2000 12:09

[cybiko_pcode.htm] miscellaneous changes reflecting recent changes made to the compiler and opcode set; many hyperlinks added for convenience

[vcc1] added recognition of the program entry point (function main)

[vcc1] fixed bug in pass1.c (function expr): correct lvalues was not recognized in expressions involving structure members ('dot' and 'arrow' C constructs)

[vcc1] data and functions are now emitted to .asm file in correct order, i.e. as they were encountered in the source file; most important implication is that exported methods are now listed in the table of exported objects in the correct order, too

[vas] fixed emitting 'short' offsets to labels: assembler used to ignore extra displacements in 'label expressions' (compiled offsets to structure fields, array elements denoted with constant indices, etc.)

[vcc1] now it is possible to derive structure from some existing one defining no new fields, as in 'struct foo: public boo {};' (this is a notation device necessary for distinguishing exported methods)

[vcc1] compiler used to ban assignments to array elements which were pointers (it was failing to recognize them as lvalues)

[vcc1] structure fields were not recognized as fields (e.g. on the right side of . or ->) within member functions of structures they belonged to

[vcc1] when searching for structure fields while processing . and -> operators, compiler did not search base structures

[vcc1] in the 'dot' operator, size of structure element was never computed, so compiler used 4-byte indirect loads and saves by default; better diagnostics implemented to catch size mismatches similar to this one

[vcc1] if structure definition was not [properly] terminated with a semicolon, and that illegal definition was immediately followed by [correct] function definition, compiler would blow up instead of just reporting syntax error

[vcc1] while building code tree, compiler (sometimes) did not recognize fields of base structures within methods of derived ones

[vcc1] within structure's method, if field name to the right of the 'dot' operator was also a field of that structure then it could be treated as a 'this'-based variable and not as just a displacement

[vcc1] compiler now issues warning rather than error if it detects comparison that needs type cast (e.g. integer with non-integer; pointer with something other than 0 or pointer to the same type; etc.)

[vcc1] if static (v.s. local or 'this'-based) array were accessed with constant indices, compiler treated that array's elements as 4-byte

[vcc1] constant cast expressions, such as ('typename') 'number', did not produce any code

[vcc1] compiler did not handle negative constants correctly; for functions, this meant ineffective code, but for static data this meant inability to use negative initializers at all

[vseq] sequence compiler now supports 'idle' loops, that is loops which just count cycles but draw nothing; such loops can be specified using negative number (or just '-' which means '-1') as 'repetition counter'

[vseq] size of stored loop records reduced from 4 to 3 bytes each

[vcc1] both post- and pre-increments and decrements were actually compiled into pre-increments and pre-decrements, respectively; in other words, post-increments and post-decrements did not work

1.0.0 04/05/2000 09:22

First public release

Vadim Sytnikov.


Known Bugs

Known problems

Known bugs / problems:

The compiler does not support initialization of a variable of type 'unsigned long' with a value that is greater than biggest 'signed long' (e.g. 'unsigned long n = 4000000000;' will fail). The workaround is to use hexadecimal representation of the "offending" constant (e.g. 'unsigned long l = 0xEE6B2800;' would do the trick).

Initializing a static pointer with address of data lying in other dynamic library or OS leads to an undefined behavior

[asm] ".export", ".actor", ".xmanager", ".xlib", ".patch", ".dl", "storegc.u", "storegs.u", "storegl.u", "patch.u", "leagb.u" left undocumented

[vcpp] __TIME__ does not take daylight saving changes into account; there is a bug in localtime() of CRTDLL.DLL (that same function implemented properly in both MSVCRT.DLL and CYGWIN1.DLL)

Future enhancements:

[vlink] process `.exp' files

[make] circular dependencies not reported as errors


Media Converter

Table of Contents

  • About Converter
  • How to Define View of Converter Window
  • How to Define Positional Relationship of Converter Main Window and Picture Adjustment Box

About Converter

Using the Converter program you can:

  • Send pictures from your computer: change them into picture files, and put them on your Cybiko computer!

  • Take your Cybiko pictures, stick them on your PC, and have some more fun with them!

Converter is a PC application that can be run at CyberLoad application by the button. Converter allows you to:

  • Convert bitmaps files (*.bmp) to Cybiko picture files (*.pic) or (*.xpic), and to send pictures to Cybiko computer.

  • Get Cybiko picture files (*.pic) or (*.xpic) to PC and convert to bitmap files (*.bmp).

  • Convert midi files (*.mid) to Cybiko music files (*.music), and to send music files to Cybiko computer

Converter consists of:

  • Converter main window;

  • Picture Adjustment Box;

  • Cybiko Picture to PC Bitmap Converter Box;

  • Music File Converter Box.

How to Define View of Converter Window

  • Choose View main menu item;

  • Press Toolbar menu item to turn on/off toolbar with Converter buttons;

  • Press Status Bar menu item to turn on/off hints at the bottom of Converter main window.

How to Define Positional Relationship of Converter Main Window and Picture Adjustment Box

  • Select PicBox main menu item.

  • Select Magnetism item to turn on/off magnetism of Converter window and Picture Adjustment Box.

When you turn off magnetism, Picture Adjustment Box will move independently.


Tutorials

How to Get Picture on Your Cybiko Computer

Table of Contents
  • Open a Bitmap File
  • Picture Adjustment

Open a Bitmap File

1. On the File menu, click Open.

2. In the Look In box, click the location of the bitmap file.

3. Below the Look In box, double-click the folder you want.

4. Double-click the bitmap file name, or type it in the File Name box.

Picture Adjustment

You can work with two types of picture files: four-color pictures (*. pic) and photo-color pictures (*.xpic). To choose the version you want to use, just choose “Photo” or “Four” in the Color group in the Picture Adjustment Box

You’ll see the bmp image in the Converters main window just like it’ll look on your Cybiko Computer. This is so you can work with it a little more if you don’t immediately like what you see!

Check Preview at Picture Adjustment Box to view picture in Cybiko Computer colors. Uncheck Preview at Picture Adjustment Box to view picture in its original colors. In non-preview mode you can use only Zoom control slider. To move the frame at the main window use keyboard arrows or move the mouse while holding left button.

You can adjust picture using:

1. Brightness

2. Contrast

3. Noise

4. Zoom

Or follow our recommendations for four-color picture.

Brightness
Drag the Brightness control slider up to make picture lighter and down to make picture darker.
Contrast
Drag the Contrast control slider up to increase picture's contrast and down to decrease picture's contrast.
Noise
Drag the Noise control slider up to increase picture's noisiness and down to decrease picture's noisiness
Zoom
At Picture Adjustment Box:
Drag the Zoom control slider up to zoom in converted area and down to zoom out converted area.
At Converter main window:
Hold Control key and press Up/Down arrow or move the mouse while holding right button.

Press to set default adjustment parameters.

Recommendations: How to adjust a four-color picture

1. Slide the Contrast and Noise controls to their lowest position.

2. Use the Brightness control slider to achieve equal filled areas of two Cybiko Computer colors (light gray, gray).

3. Drag the Contrast control slider up until you see another two Cybiko Computer colors.

4. Achieve equal filled areas of four Cybiko Computer colors with the Contrast control slider.

5. Use the Noise control slider to set optimal level of noisiness.


Tutorials

How to Get Picture File from Cybiko Computer to PC

Table of Contents

  • Copying or Moving File from Cybiko Computer to PC
  • Opening Picture File (*.pic or *.xpic)
  • Saving a Converted Picture

Copying or Moving File from Cybiko Computer to PC

First you have to do is to get the picture in your PC:

  1. Return to the CyberLoad program.
  2. Check off the file you want to copy/move and press <Copy>/<Move>.
Opening Picture File (*.pic or *.xpic)

Run the Converter from the CyberLoad program.
  1. On the File menu, click Open.
  2. In the Look In box, click the location of the picture file.
  3. Below the Look In box, double-click the folder you want.
  4. Double-click the picture file name, or type it in the File Name box.
Saving a Converted Picture

Press <Save Bmp> to save picture you see in the view box. Standard Window’s “Save As” box will open. Here you can select the directory and file name you want for your picture.

Press <Close Box> to close the conversion box. If you check “Close on Save” option then when you save bmp file the box will automatically close.


Graphics_ctor

Working With Music Files

Table of Contents
  • Restrictions
  • Opening MIDI File
  • Music Adjustment

Restrictions

Cybiko Computer plays only one track of Music at a time.
So, before converting a MIDI music file to the Cybiko Computer music file format, you need to:

  1. Choose which track you want to convert, usually you want the main instrument.
  2. Create a new MIDI file (in your MIDI editor) consisting only of this one track, or simply delete the tracks you don’t want and save the MIDI file with a new name.
  3. Convert this new MIDI file with the Cybiko Computer MIDI file converter.
Opening MIDI File

Using the Converter program you can:

  1. On the File menu, click Open.
  2. In the Look In box, click the location of the MIDI file.
  3. Below the Look In box, double-click the folder you want.
  4. Double-click the MIDI file name, or type it in the File Name box.

You will see the Music File Converter Box.

Music Adjustment

Music File Converter Box presents you the option to adjust your music file:

Note Separation
You can make the staccato effect for the notes of equal pitch going one by one. Check off the Note Separation check box and set the number in the edit field that determines how many ticks (one tick is equal to one-hundredth of a second) there will be from the note duration for a break between the next note with the same pitch.

Break Options
To make a converted file more musical, there are interesting and useful options in the Music File Converter Box: Break After and Break Length. You can set their parameters in the number of ticks (one tick is equal to one-hundredth of a second) for the pattern of tremolo sounding of the converted file.

Check off the Break After check box and set in the edit field the number which defines the time between breaks in ticks. The Break Length check box will be checked off automatically with the default parameter equal to 1 tick.

Set in the edit field of Break Length the time of the break you want in ticks.

Transposition
You can transpose the MIDI file to definite numbers of semi-tones. Check off the Transpose check box and set the number of semi-tones in the edit field. The positive numbers pitch the audio frequency up; the negative numbers pitch the audio frequency down.

Note: The MIDI file can play 128 different notes. Cybiko Computer can play 99 different notes. To convert a MIDI file to a Cybiko Computer music file correctly, you need to set the transposition number so the converted music file will be in Cybiko Computer audio range.

If you check off the Auto-transpose check box, the program will transpose the converted file automatically to set the music file in Cybiko Computer range.

To listen to how music will sound on your Cybiko Computer in the Music Composer application press <Play>.
Use <Pause/Resume> to pause and resume playing. Press <Stop> to stop playing.
Press <Save As…> to save music on your PC. The standard Windows “Save As” box will open. Here you can select the directory and file name you want for your tune.
Press <Send to Cybiko Computer> to send the music file to your Cybiko Computer.


Overview Standards

Interface Standards

Cybiko, Inc. has prepared more than 200 service applications and games for release. These applications help attain a wide range of purposes, but they have uniform principles of user interface construction. Therefore, the menu, the lists, and the dialog box look and function identically in all applications. This is important, and it averts numerous problems. The developer might have the problem of debugging the applications, and the user might face the clarity problem.

This section contains recommendations for developing your own Cybiko applications. By adhering to these recommendations, you will follow the principles of forming the applications interface which the Cybiko, Inc. programmers use. This section is broken into subsections. The largest subsection comprises a set of pages describing dialog box types. It is called "Dialogs Views". You will find recommendations on choosing a level of the game, its beginning, interruption, and completion, as well as the initial conditions. You will find the rules concerning applications titles and the handling of sound in separate pages. More rules are assembled in the "Miscellaneous" section. Note that the interface standards are still in the development stage and they are being supplemented. If you have a question, analyze the application interfaces on your Cybiko computer or the interfaces which you can download from www.cybiko.com/download. You can also seek help in our technical support department.


Root section (Main Desktop)

The screen of the root section contains icons of all main subsections and applications. The root section boots right after the device is turned on. The root section is intended for navigating by the end-user in the main subsections. The subsections icons and applications are icons of size 48 x 47. The signatures under the icons show the current subsection's icon name or the current application's name. The active icon is the icon with a shadow. Above the set of icons is the inscription "Main Desktop" with alignment in the center. In the left lower corner under the set of icons there is an indicator appearing as smiling human muzzles. It shows the number of people who are participating at the present time. The device starts to react when the number of participants increases. It appears either as a vibration or as a sound (depending on what has been selected in the system parameters). The indicator of the time in "a.m." or "p.m." modes is located at the center under the set of icons. The Power Saver indicator is located in the right lower corner under the set of icons. It shows the level of charge. Also the indicator denoting whether the speaker is in the speaking or non-speaking mode is located in the right lower corner under the set of icons. It depends on what sound has been selected in the system parameters. Note that the human muzzle indicators, hours, Power Saver and the speaker are saved at the site of transition from "Main Desktop" to such subsections as "Application" and "Games." All set indicators disappear upon the loading of such applications as "You and Me," "Chat," "People," and "Settings." In the initial state the first icon is active (the icon at the center of the screen). The icon name is centered underneath the icon.

The keyboard layout of operation using the "Main Desktop" only is as follows:
  • Keys <LEFT ARROW> and <RIGHT ARROW> mean movement from one subsection to another and movement from one application to another in a clockwise circle. Only three icons can be located on the Screen at one time. The center icon is always the active one when moving icons to the right or left. The name of a subsection or an application is centered below the icon. Movement of the root icons is in a clockwise circle.
  • Key <TAB> duplicates operation of the right arrow.
  • Keys combination <SHIFT>+<TAB> duplicates operation of the left arrow.
  • Key <ENTER> loads applications such as "You and Me," "Chat," "People," "Settings," or a change of level in such subsections as "Application" and "Games."
The other keyboard does not operate.


The menu and the list

The menu and the list (designated "objects") have identical behavior but differ in appearance and assignment. Each item from the menu or list represents three areas:
  • The icon field.
  • The name field.
  • The value field.
There are questions about the names of the interface structural units when using the menu and the list. Since the interface structural units contain the given object standards, it is expedient to enter the following terms:
  • Section list (Slist) - uses the menu as a rule and is the main screen for such applications as "You & Me."

    About you
    About me
    My CyPage
    Business Card
    My Photo

  • Extended list (Xlist) - uses for its parameters definitions, application customizations, mapping of lists of people, etc.

    Meeting purpose | Romantic
    My nick name | Unknown
    I am | a girl
    Birthday, day | 2
    month | Jan
    year | 1991
    Height, ft | 5
    in | 9
    Weight, lbs | 65
    Hobby1 | Cy-B
    Hobby2 | Cy-B
    Hobby3 | Cy-B
    Secret field1 | Secret
    Secret field2 | Secret
    Secret field3 | Secret
In the left field can appear either an icon or no icon. The entry in the center field must leave at least ten vacant letter spaces; in the third field, at least two letter spaces must be left.

The initial state:
1. | The uppermost choice is active in the menu. The icon field and item name field are inverted. The value field is not inverted.
2. | The upper item of the list is active in the list. Only the item name field is inverted.

Lists should be scrolled by the <FN>+<UP ARROW/DOWN ARROW> combination keys. Lists should not be scrolled by the <LEFT ARROW/RIGHT ARROW> keys.

The keyboard layout of operation of the menu or the list is as follows:
  • <Subsection keys> switches from the current menu or the current list to the main menu of an appropriate subsection.
  • Keys <UP ARROW> and <DOWN ARROW> move along the menu items or the list items.
  • Key <ENTER> has following features:
    • 1. | If a menu or list item branch is designated, there is a transition to the sub-menu or sub-list; if not, the appropriate application is initiated. The text of an item should be ended by "…" characters.
2. | If a branch is not stipulated, there is a transition to the previous level of branching (an exit and a save).
  • Key <SELECT> is accessible if input of choice value is designated. The value can be selected by pressing <SELECT>. If the keyboard input is designated, the appropriate keyboard input section is put into operation.
  • Keys combination <CTRL> + <SELECT> are accessible if change of the current menu item from the icon or list field is designated. The designated icons are scrolled in a clockwise circle.
  • Keys combination <CTRL> + <ENTER> are accessible if alternate branching of the menu or list is designated.
  • Key <INS> is accessible if insert of a new item through form filling is designated (see "Organizer").
  • Key <DEL> is accessible for deleting list or menu items.
  • Key <ESC> has the same function as the key <BACK>, except when a user moves up to the main section menu.
  • Key <?> designates "help" at each level.
  • The <Alpha-numeric keyboard> has the following features:
    1. | If from the initial state of value of choice, any of alphanumeric keyboard keys are pressed, it will completely annihilate the previous value of choice (the mode of complete replacement). Then the cursor is placed on the first character of the value field of choice. Thus the inverted value field of choice disappears.
    2. | At input the cursor is BEHIND the last character typed.
    3. | When the limit of the number of characters selected for each field has been reached, then if any alphanumeric keyboard button is pressed, nothing will appear on the screen. Text editing is executed by moving through the text by <LEFT ARROW> or <RIGHT ARROW> (see lower).
    4. | If from the initial state of value of choice <LEFT ARROW> and <RIGHT ARROW> are pressed, then the color inversion of the value field of choice disappears, and the cursor moves under the text of a reference value of choice (edit mode). Thus the alphanumeric keyboard works in an insert or over-write mode. It depends on the <INS> station. Thus, all rules that were described in item 3 apply here.
    5. | Keys <LEFT ARROW> and <RIGHT ARROW> operate under the typed text after switching to the over-write mode or to edit mode from the initial state. The right boundary is the font letter space behind the last character and the left boundary is the first text character.
    6. | The text scrolls to the right and left if it does not find room in the value field of choice during a set.


The local menu

As contrasted with the list and the menu, the local menu is a visual deckhouse of active applications. The local menu has the following distinctive features:
  • The local menu displays additional characters during operation of an application.
  • The local menu gives a multiple choice of operations in contrast to the dialog box and messages windows.
  • After making a choice the local menu disappears and the user is returned to the main application screen.
The local menu appears at the top of the application screen and includes a header and items. The header is for auxiliary messages and in contrast to the standard header and is shown in black background. The header font is white bold and the header text is flush left. If there is not room on the screen vertically for the local menu items, white color scroll arrows <upwards/downwards> will be designated in the right portion of the header.
Items of the local menu cannot be edited; however, their appearance is similar to that of the list items. Items of the local menu have only one field - the name field - as contrasted with the list items. The name font is in boldface. If the local menu item can produce a dialog box, then the item must end with an ellipses [...] (for example, the "Death…" item in the "Life" application in the following local menu).

Edit rules for
Neighbors
Death...
Birth

Let's enter the following terms:
  • "Lmenu" the first kind - It's the local menu with rounded corners and with a header. (In the figure above, there is a minor error; the corners should be round.)
  • "Lmenu" the second kind - It's the local menu with rectangular corners and without a header. For example, the local menu in the "Chat" application which appears when we select a partner:

    all
    <Update>

In any current local menu item, the background and foreground colors are inverted. In the initial state the uppermost item of the local menu is active.

The local menu is located at the top of an application screen. The width of the menu is dictated by the maximum length of the item's name + 16 pixels. Limitation of height size is the number of items plus 4 pixels below.

The keyboard layout of operation using the local menu is as follows:
  • Keys <UP ARROW> and <DOWN ARROW> are used to move items up and down.
  • Key <ENTER> is used to execute a dialog box or to select any operation.
  • Key <ESC> is used to return to the application.


The line editor

The line editor is the elementary text editor that is intended for input of information on a single line. It is used to input choice values of the menu (or the list) and is also the structural component of the Chat and the text Editor. The entire alphanumeric keyboard is accessible. Function keys (such as described for keyboard layout by operation from menus (list) are unavailable.


Dialog boxes

At execution of some applications functions (for example, terminating the text Editor, Musical Editor, Graphics Editor etc.) it is necessary to load the dialog box without closing the current application screen. The dialog box is visually located at the top of the current application screen or a Navigation interface structure.

The dialog box consists of the operations Text. It is necessary for fulfilling the current stage of an applications operation. The dialog box also consists of several operations controls, for example, confirmation of operation, cancellation of operation, or cancellation of the dialog box.

The operations text is always centered at the middle of the area and is placed between the dialog box boundaries and the nearest operations control boundaries. The operations text font is the standard font. Subdividing the text is permitted. Operations controls are located either across the bottom of the dialog box or on a vertical in the left part of the dialog box.

Control size is a maximum of 1/3 of the width of the dialog box. Controls are placed at equal distances horizontally between the dialog box boundaries. The control size is dictated by the size of the dialog box. Subdividing the text is allowed in the controls area. The control size on a vertical is dictated by the font size (plus 2 pixels from above and from below up to the controls boundary).
In the initial state the focal point is on the control that confirms an operation.

Keyboard layout by operation with dialog boxes is as follows:
  • Key <TAB> is used to switch between controls in a clockwise circle.
  • Keys <LEFT ARROW> and <RIGHT ARROW> are similar to <TAB> key.
  • Key <ENTER> is used to execute the current control function.
  • Key <ESC> is used to exit from the dialog box.


The information dialog boxes

One variation of the dialog box is the information dialog box. The information dialog box consists of an operations text and one control. The information dialog box's assignment is to inform the user about system events or about an application's rules.

In the initial state the focal point is on the dialog box control.

Keyboard layout by operation with information dialog boxes is as follows:
  • Key <ENTER> is used to execute control function.
  • Key <ESC> is used to exit from the information dialog box.
The other keyboard is not in operation.


Dialog boxes with an edited text field

Another dialog box variation is dialog boxes with an edited text field. Dialog boxes with an edited text field consist of an operation text, text field and operation controls.
  • An operation text serves to explain the text field input. Its location is the same as the location of the operation text in the dialog boxes (see above).
  • The text field serves as a keyboard input for the information appropriate to the requested operation. The text field is centered. The text has the possibility of scrolling horizontally.
  • The operation controls serve to confirm/cancel the text field of operation text. Control sizes and configurations are the same as those for the messages windows.
The text field is active in the initial state. If there is a text by default, then the background and foreground colors are inverted.

The keyboard layout by operation using dialog boxes with an edit field is as follows:
  • <TAB> - is used to move across a text field control and across operation controls in a clockwise circle.
  • <LEFT ARROW> and <RIGHT ARROW> - when the text's field is active, there is the same pattern of movement as in the input system. When the operations controls are active, there is movement from one to the next in a clockwise circle only.
  • <ENTER> - when the text field is active, there is movement to the first operations control, which is either the left-most control or (in the case of vertical controls placement) the uppermost control. When this movement takes place, the change is saved in the text field. When operations controls are active, the execution of an operation is always appropriate to the control.
  • <ESC> - when the text field is active, there is movement to the first operation control, and the changes are saved in the text field. When operations controls are active, the dialog box disappears from the screen


Dialogs Views

The user interacts with the application through the dialog box. The Cybiko, Inc. programmers use eleven dialog box types. The dialog boxes fulfill a wide range of functions, notably:
  • The Types and Form of Dialog Windows
  • Awaiting Reply from a Remote Device
  • Awaiting the Connection with a Remote Device
  • Interruption of Connection with a Remote Device
  • Query for Information from a Remote Device
  • Notification of the Move Transfer in the HOT SEAT Regime
  • Suggestion of a Draw
  • Rejection of a Draw
  • A Draw
  • Exiting the application at a Remote Device Situation
  • End of the Game Message
  • Exit the Game Message
  • Features of Working with Dialog Windows
  • Help
These dialog boxes inform the user about upcoming events in the system. They are created uniformly. The cDialog class object is created. Place the necessary message and the type of buttons in its parameters.

Moreover, the "Dialogs Views" subsection contains the recommendations on The Form and dialog box types and on aspects of working with dialog boxes and with a Help.


The Types and Form of Dialog Windows

1. | All dialog windows that are in essence double-button windows must have only two buttons. Unless there is a special purpose, the left button should confirm the action and the right button should either cancel it or suggest an alternative.
2. | All dialog windows must appear only against the background of the gaming field. No dialog windows should appear in the Help window or on a blank screen.
3. | Sound must accompany the appearance of dialog windows. Sound is set in the style parameter of the cDialog class constructor.


Awaiting Reply from a Remote Device

Situation

Waiting for the reply from a user of a remote device after a query (e.g., an invitation to participate in a game) has been sent out.

Dialog Text

"Waiting for answer..." (str_Draw_waiting)

Responses to the cancellation via <Esc>

a) | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
b) | Exit to root if the application was started via an invitation of a remote user.


Awaiting the Connection with a Remote Device

Situation

In two-player games, the process of establishing the connection begins after a partner has agreed to play. Both users' devices must display the "Waiting for link..." dialog window.

Dialog Text

"Waiting for link..." (str_Waiting_link)

Responses to the cancellation via <Esc>

a) | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
b) | Exit to root if the application was started via an invitation of a remote user.


Interruption of Connection with a Remote Device

Situation

In two-player games, the process of establishing the connection begins after a partner has agreed to play. If the application fails to connect to a remote device, the "Link Off" dialog window appears.

Dialog Text

"Link OFF" (str_Link_off)

Button

<Quit> (mbQuit)
<Cancel> (mbCancel)

Responses to the buttons

<Quit> |
- | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
- | Exit to root if the application was started via an invitation of a remote user.
<Cancel> |
- | The field of the game is displayed if the game began. However, the game cannot be continued. Then the application is exited via the standard dialog of the exit.

 Responses to the cancellation via <Esc>

Duplicates the response to the <Cancel> button.


Query for Information from a Remote Device

Situation

Dialog window with the text "Wait, please..." must appear during the reading of information from a remote device.

Dialog Text

"Wait, please..." (str_wait + str_please)

Button

<Cancel> (mbCancel)

Responses to the <Cancel> button

Interruption of the query.

Responses to the cancellation via <Esc>

Duplicates the response to the <Cancel> button.


Notification of the Move Transfer in the HOT SEAT Regime

Situation

Dialog window with the text "First player's move" or "Second player's move" must appear during the transfer of the move in the Hot Seat regime.

Dialog Text

"First player's move"
"Second player's move"
or
"Turn of Player 1"
"Turn of Player 2"

Button

<OK> (mbOk)

Responses to the <OK> button

Transfer of the move to the partner.

Responses to the cancellation via <Esc>

Duplicates the response to the <OK> button.


Suggestion of a Draw

Situation

Dialog window with the text "Your partner suggests a draw, do you agree?" must appear if one of the partners wants a draw.

Dialog Text

"Your partner suggests a draw, do you agree?" (str_Draw_suggestion)

Buttons

<Yes> (mbYes)
<No> (mbNo)
(mbNoEsc)

Responses to the buttons

<Yes> - | to accept the draw and end the game via the standard exit dialog.
<No> - | to reject the draw and continue the game.

Responses to the cancellation via <Esc>

Duplicates the response to the <No> button.


Rejection of a Draw

Situation

Dialog window with the text "Draw rejected!" must appear if you want a draw but your partner doesn't.

Dialog Text

"Draw rejected!" (str_Draw_rejected)

Button

<OK> (mbOk)

 Responses to the <OK> button

to return to the game.

Responses to the cancellation via <Esc>

Duplicates the response to the <OK> button.


A Draw

Situation
Dialog window with the text "Draw." must appear if both you and your partner want a draw.

Dialog Text

"Draw." (str_Draw)

Buttons

<Quit> (mbQuit)
<Cancel> (mbCancel)

 Responses to the buttons

<Quit>
a) | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
b) | Exit to root if the application was started via an invitation of a remote user.
<Cancel>
- The field of the game is displayed. Then the application is exited via the standard exit dialog.

Responses to the cancellation via <Esc>

Duplicates the response to the <Cancel> button.


Exiting the Application at a Remote Device Situation

Situation

Dialog window with the text "Your partner surrendered.\nYou WIN!" must appear if the partner exited the game.

Dialog Text

"Your partner surrendered.\nYou WIN!" (str_Partner_surrender)

Button

<Quit> (mbQuit)
<Cancel> (mbCancel)

Responses to the buttons

<Quit> |
- | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
- | Exit to root if the application was started via an invitation of a remote user.
<Cancel> |
- | The field of the game is displayed if the game began. However, the game cannot be continued. Then the application is exited via the standard dialog of the exit.

 Responses to the cancellation via <Esc>

Duplicates the response to the <Cancel> button.


End of the Game Message

Situation

At the end of the game a dialog window appears with one of the texts listed below. The text depends on the type of game.

Dialog Text

For the HOT SEAT regime:

- | "First player WINS!" (str_1st_win)
- | "Second player WINS!" (str_2nd_win)

For playing with CYBIKO, playing with a remote partner, and in one-player games without the score count:
- | "You WIN!" (str_You_win)
- | "You lose." (str_You_lose)

For one-player games in which the result is measured in the number of
points scored:
- | "Best Score - number of points"
- | "Last Score - number of points"
- | "You have the best" - if a record was set.
 | For example: "Best Score - 100" "Last Score - 200"

 Buttons

For the HOT SEAT regime:

- <Quit> (mbQuit), <Cancel> (mbCancel)

For playing with CYBIKO or with a remote partner:
- <Quit> (mbQuit), <Cancel> (mbCancel)

For games without a partner:
- <Quit> (mbQuit), <Restart> (mbRestart)

Responses to the buttons

For the HOT SEAT regime, playing with CYBIKO, or playing with a remote partner:

<Quit> |
- | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
- | Exit to root if the application was started via an invitation of a remote user.
<Cancel> |
- | The field of the game is displayed if the game began. Then the application is exited via the standard exit dialog.

For one-player games:
<Quit> |
- | to exit into root.
<Restart> |
- | to begin a new game.

 Responses to the cancellation via <Esc>

The game field is displayed. However, the game cannot be continued.


Exit the Game Message

Situation

In the process of exiting the game, a dialog window appears with the following text: "Do you really want to quit?"

Dialog Text

"Do you really want to quit?" (str_Really_exit)

Buttons

For one-player games:

- <Quit> (mbQuit), <Restart> (mbRestart)

For one-player games, if <Restart> does not make sense:
- <Quit> (mbQuit), <Cancel> (mbCancel)

For two-player games:
- <Quit> (mbQuit), <Draw> (mbDraw)

For two-player games, if a draw cannot be suggested:
- <Quit> (mbQuit), <Cancel> (mbCancel)

Responses to the buttons

For one-player games:

<Quit> |
- | to exit to root.
<Restart> |
- | new game begins.

For one-player games, if "Restart" does not make sense:
<Quit> |
- | to exit into root.
<Cancel> |
- | Returning to the game if it is under way. Returning to root if the dialog appears before the dialog appears before the beginning of the game.

For two-player games:
<Quit> |
- | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
- | Exit to root if the application was started via an invitation of a remote user.
<Draw> |
- | Suggestion of a draw.

For two-player games, if a draw cannot be suggested:
<Quit> |
- | The field of the game is displayed if the game began. Then the application is exited via the standard exit dialog.
<Cancel> |
- | Duplicates the <Quit> button.

For the HOT SEAT regime, playing with CYBIKO, or playing with a remote partner:
<Quit> |
- | Exit to the Select Partner menu, if the application was started via the Select Partner menu.
- | Exit to root if the application was started via an invitation of a remote user.
<Cancel> |
- | The field of the game is displayed if the game began. Then the application is exited via the standard exit dialog.

Responses to the cancellation via <Esc>

Returning to the game if it is under way. Returning to root if the dialog appears before the dialog appears before the beginning of the game.


Features of Working with Dialog Windows

  • If <Enter> is pressed in the field of information input, the focus is not shifted to the <OK> button. Moreover, the <OK> button is not animated when pressed.


Help

1. | Help does not appear if any dialog window is displayed on the screen.
2. | The Help title must be short enough to allow scrolling with the up/down control. If an application has a long name, it should be shortened: e.g., "checkers" instead of "wireless checkers".
3. | If Help is started from the file selection window, the files must retain their places when Help is exited.
4. | The dialog windows, which should appear simultaneously with Help, are not written over Help. However, this rule does not apply to the dialogs that are initiated by the service programs.
5. | Movement in logical games is not necessary be suspended when Help is started.


Level Selection in Games

1. If it is allowed to use the device as a partner in a two-player game, or both partners can play on one device, the Partner Selection menu must contain the "CYBIKO" and/or "HOT SEAT" lines. To add these lines to the list of identified devices, use the third parameter of the select_game_partner function.

2. The level of the computer as a partner must be selected from Cybiko-master, Cybiko-beginner, etc. These computer partners, similar to "HOT SEAT", must be placed at the bottom of the list.


The Start of the Game

1. If an invitation for participating in a game arrives, the current application is exited after any functional key or the <OK> button is pressed. A pertinent dialog box appears if information must be saved in the current application. If the player presses <Save>, the process can be cancelled by the <Esc> button; e.g., if a subsequent message notifies the player that a file with such a name already exists and asks the player if it must be overwritten.
If the player agrees to play but the approximate 1.5-minute timeout expired during the saving, the game is not started after the exit from the current application.

a) If incorrect data is entered, a pertinent message is displayed during saving.

b) After all steps of the saving process are completed, a transfer is made to a game for which the invitation was received.

c) No response to the pressing of the functional keys must be made during the interval between the acceptance of an invitation to play and a transfer to the game. No other invitations must be displayed during this interval.

d) At all times except the interval described in c), functional keys can be used to exit the dialog boxes.

e) <Esc> is used to cancel the invitation to play.

2. The game begins when the game file is displayed on the screen(s) of the player(s) device(s). The "Waiting for link..." box must appear while a connection between the devices is being established.


End of the Game

1. The suggestion of a draw is considered a separate move. The draw query is sent, a reply is awaited, and a move can only be made after the reply is received.


Initial Position

1. The initial position of the cursor and the mode of its movement must be chosen so that they are convenient for the player whose turn it is to move. After the move, the cursor remains in the position from which the move was made.

2. The move sequence and item color are selected randomly.


Names

Messages, Titles, Names

1. If messages are displayed in bold, both small and capital letters can be used in the beginning of the word. If the font is regular, the capital letter must be used.

2. If the title of the menu (list) contains more than one word, it must be in bold and in the capital case. Local menus are an exception; e.g., the Local menu in the Life application. Bold is not used and only the first word of the title begins with a capital letter; other words of the Local menu title begin with small letters.

3. The file names of applications and games must correspond as closely as possible to their names in the root. Limitations are set by the file system and the file manager. The file names must not go beyond the borders of the visible field in the file manager.
For example:

Clock_Solitaire, Men's_Room

4. The file name must begin with a capital letter. If it contains several words, each of them except prepositions, conjunctions and articles must begin with a capital letter. The underlining dash must be placed between the words.
For example:

Tower_of_Hanoi


Sound

1. The sound of the alarm clock is given priority over other music which is being played at the moment.


Miscellaneous

1. | If the game is accompanied by music, it does not stop if a key is pressed.
2. | The "Link OFF" message appears one minute after the connection was interrupted.
3. | A record is registered only if the score is higher than the previous record score.
4. | Movement within fields must proceed in cycles; e.g., after reaching the left-hand corner, an item must turn up on the right side.
5. | It's up to the developer to choose a key for the item selection and its move.
6. | The player cannot make a move while waiting for the partner to move.
7. | If a key is pressed for a length of time, the response should be the same as if it were pressed and instantly released. When necessary, exceptions are permitted.
8. | Lists are scrolled by using <Fn>+<Up/Down arrows>. No scrolling by <Fn>+<Right/Left arrows> is permitted.
9. | If a record score was attained, it is saved during an emergency exit from the game.
10. Saving results in two-player games:
a) | Three files from three different devices can simultaneously be saved on one device.
b) | Devices are identified by their ID.
c) | Old files are gradually deleted when the new ones arrive. If a file registering a particular partner already exists, the next file is saved in its place. It is treated as the first of the two files.
d) | The game information is saved automatically only when the link is off.
e) | If files were saved on both devices, a file with a higher number of registered moves is loaded.
f) | If the game is over or one of the partners loses, the corresponding previously saved file must be deleted.
11. | If a dialog box appears while items are moving, the movement is suspended. The game is resumed at the suspended point. If a message about the partner's move arrives while the dialog box is displayed, the message is shown after the box is exited.
12. | The dialogue "First player's move" ("Second player's move") must precede the transfer of moves in the "HOT SEAT" regime.
13. BEFORE THE GAME STARTS, no dialog boxes must be used to exit the Select Partner and Select Game menus.


Tutorials

Cybiko, Inc. values the time of Cybiko applications developers. Cybiko, Inc. offers a set of special programs designed to help the developer quickly get the skills necessary for programming Cybiko applications. These programs show all interface objects in operation. Such objects include the list, the menu, the local menu, the dialog box and the dialog box with an editing field. The programs demonstrating operations with the interface objects are compiled in the Interface Guide subsection.

Almost all Cybiko applications are graphics. So, the Graphics Effects & Sound subsection gives examples of operations with elementary graphics objects (pixel, line, filled and blank rectangles) as well as with complex graphics objects - bitmaps. An example of operation with sound and vibration is also provided.

The demonstration programs for operations with Threads will be added later. Also, you can find links for several completed and fully-functional applications. You might already have some of applications on your Cybiko computer. If not, you can download it from our site.

All programs are commented upon so that the developer can easily understand the offered code.


Steps

Table of Contents

  • Interface Guide
  • Graphics Effects & Sound
  • Accessing Serial Port
  • Dynamic Library
  • Complete Applications

Interface Guide

The Interface Guide subsection offers five examples of operation with the interface objects. These objects include the list, the menu, the local menu, the dialog box and the dialog box with an editing field. These examples are designed so that every subsequent example includes the functionality of the previous one:
  • Step1 - creation of the minimum container program capable of functioning on your Cybiko computer. It serves as a frame for all Cybiko applications.
  • Step2 - an exit from the program through the "Do you really want to quit?" dialogue is added to the previous step.
  • Step3 - the stub elementary dialog box is added to the previous step. Stub appears upon clicking on the local menu items.
  • Step4 - the local menu of the previous step causes the appearance of the list and menu objects upon clicking. Menu and list items cause the appearance of the elementary dialog box - stub.
  • Step5 - the list object of the previous step is modified so that its items could be added through the dialog box with an editing field. All the rest remains unchanged.
In addition, an example is provided that demonstrates serial port communications.

All examples are placed in the 'demos/tutorials' directory.

Accessing Serial Port

The serial port is a native part of the Cybiko computer. The Cybiko SDK provides an API for serial port access. All API functions are implemented in ComPort.dl. This library must be present on your Cybiko computer for the interface to work properly.
The "serial" tutorial shows some basic methods of accessing a serial port, including initialization and data reading and writing.

The example is placed in the 'demos/tutorials' directory.

Dynamic Library

The Dynamic Library tutorial demonstrates interaction between an application and a dynamic library. To run this tutorial, you must upload both dynapp.app and dynamic.dl to your Cybiko computer first.

The example is placed in the 'demos/tutorials' directory.

Graphics Effects & Sound

Please, study the Interface Guide part before working with the Graphics Effects and Sound part. The previous subsections contain the information, which is necessary for understanding this subsection.

Almost all Cybiko applications are graphics. Therefore, the Graphics Effects and Sound subsection gives examples of operation with elementary graphics objects (pixel, line, filled and blank rectangles) as well as with complex graphics objects - bitmaps. An example of operation with sound and vibration is also provided.

The example is placed in the 'demos/tutorials' directory.

Complete Applications

This part provides sources for the completed and fully-functional applications: Tic-Tac-Toe, Highway Hitman, Fox Hunting, CySpider and Lizard Luncheon.

Highway Hitman game is an overhead, side-scrolling road battle for one player. The object of the game is to destroy as many other vehicles as possible, while avoiding being pushed off of the road.
More Information...
Tic-Tac-Toe is a 2-player strategy game (hot seat, or against the Cybiko). The object of the game is to be the first player to claim 3 squares, horizontally, vertically, or diagonally.
More Information...
Fox Hunting is a logical game. The aim of this game is to retrieve foxes hiding all over the game board.
More Information...
CySpider is a single player game. The ultimate goal is to pass as many levels as you can. You control a spider that can move on the playing field in different directions. Your object on each level is to capture as much of playing field as possible by cutting off pieces of the screen and spinning a web on each part.
More Information...
Lizard Luncheon is a single player game. The object of the game is to eat all the flies in each level in order to pass to the next level and prevent the lizard from starving to death. For each fly that you eat, you will get 1 point. The number of flies increases in each next level.
More Information...

You might already have these applications on your Cybiko computer. If not, you can download them from our site. All functional aspects of these sources have commentaries. If any fragment of these sources is unclear, you should look through the two previous parts, notably Interface Guide and Graphics Effects and Sound. Or, look through the appropriate sections of the Cybiko SDK.
All examples are placed in the 'demos' directory.


Processes and Modules

API Reference

You may browse the Cybiko SDK Reference in the following ways:

  • as a list of functional groups,
  • as an alphabetical list,
  • as a class hierarchy.
CyOS is a full multitasking operational system. CyOS main features:
  • Preemptive multitasking
  • Memory management system
  • Graphics system
  • File system
  • Dynamic module loading
  • Dynamic linking
  • Means of interdevice communication
The CyOS functionally represents a multitask environment with an interprocess interaction. It includes peripherals access, a file system, a graphics support, sound, dynamic loaded units, applications archives, and means of information transmission via radio channels.

CyOS handles a task comprising one or several threads, or processes executed in pseudo-parallel as in displaced multitasking. The synchronization of threads is carried out by Mutex, Flag, and Flagex. A thread can be in the process of fulfillment, or queuing for fulfillment, or hibernating ahead of an event as in a timer.

The sending of messages addressed to processes on other devices represents the network exchange. The transmission is carried out through a radio channel with automatic assembly/disassembly of packages and a notice of delivery.

Application are located on a file device as archives comprising several files. An archive includes a module under execution, resources files, and application description files in the oblate sort. When an application is started from the archive, the system extracts and unpacks the module under execution in its memory.

The application usually creates an object of the main process, bans outloading of the module from the memory, and returns the control to OS. After the initialization of an internal state, the created process transfers to the expectation of messages. The processor time is not spent on it. When a message arrives, the process revives, processes the message, and returns to the expectation mode.

Dynamic linking allows storing of frequently used components in separate executable modules, thus saves both long-storing device memory and RAM. CYBIKO gives a standard set of such modules.

System Pack is a set of standard interface modules and dynamic libraries. The main goal of System Pack is to provide uniform user interface in all applications.

There are currently seven libraries in the System Pack: Settings, Locales, Finder, Servers, Power Saver, CyWin, and Custom Dialogs. These libraries are intended to help programming in such features as communication with people, running applications, storage of various configuration data, handling different locales, management of system power, and graphics user interface.

All important system configuration settings are contained in specially organized storage. You can easily access or change these settings through the Settings library. If you need to display the current time for the user, you can take advantage of the Locales library because time is different for different countries. Using the Finder, you can determine how many people are currently around you and find out their nicknames and other data through a few function calls. Almost every application requires various data windows such as dialog boxes, forms, menus, and lists to display information to the user in a suitable form. The CyWin library can help you solve these tasks.

Service applications included in the System Pack provide a basic set of necessary user functions. They allow easy graphical management of programs on your Cybiko computer, store information about you and your friends, search for people, configure systems, and so on.

Happy programming!

The SDK Team


Module Index

API Groups

When it comes to developing a good, full-fledged application or game, the best possible starting point is to get an existing tutorial or sample application (bundled with SDK) and rework/complete it with desired features. While implementing desired functionality, you may want to consult the page you're reading now. The following API Groups list structures, functions, defines, and global variables by categories. Please note that many important structures have large sets of methods which you could browse by following a link to respective structure. Most important structures are mentioned in the descriptions of corresponding groups.
System

Processes and Modules
These structures and functions are used to control the application as a whole. You may want to look at cWinApp and module_t structures.

Synchronization
Synchronization objects are used to synchronize access to shared objects. In many cases, you can use the Mutex structure.

Memory Management
CyOS routines you can use to allocate, manipulate and free memory.

Time-related
Some functions for setting and changing the date and time. Please look at the Time structure.

Sound, Music and Vibration
These structures are used to control sound, music and vibration in the Cybiko computer. Most music control methods can be found within the description of the MSequence structure.

Communications

Messaging
These functions and structures are used to send messages between applications, including those running on different Cybiko computers. You may also want to examine the Message and Buffer structures.

Selecting Remote Partners
These structures allow the user to find a partner for a multiplayer game.

Finder-related
With these structures, you can gather information about the Cy-environment (that is, the other people and Cybiko computers in the vicinity). Finder is probably the most important of these structures.

Low Level
Some low level communication functions. Don't use these functions if you don't know exactly what are you doing.

Graphics

Drawing Primitives and Screen Manipulation
These structures and functions are used for drawing various graphical primitives and displaying them onscreen. Please pay special attention to the DisplayGraphics and Graphics structures.

Bitmaps and Bitmap Sequences
The Bitmap structure is used for work with a single bitmap, while the BitmapSequence is used for work with a Bitmap array. (see Bitmap and BitmapSequence).

3D Graphics
These functions implement Wolfenstein3D/Ultima Underworld style graphics -- they simplify creation of your own 3D worlds. Please, pay special attention to the cy3d_draw_sprite() and cy3d_draw_wall() functions.

Fonts and Text
Some structures for work with text (please pay attention to Font structure).

Interface Elements

Application
These structures represent applications' major building blocks. In fact, your application is an instance of cWinApp (please note that module_t structure contains m_process field that is a pointer to 'your' instance), which is important, since it allows for the usage of forms, controls, as well as other interface elements.

Base Structures
The most basic structures (cObject, cClip, etc.) that serve as a base for the rest of this group, save the AppGeneric and the cWinApp structures. Please pay special attention to the cEngine structure that provides a couple of quite useful services (also, note that there exists a single, unique instance of such an object in the system).

Forms & Containers
Forms (cCustomForm, cFrameForm) are structures that can be used as containers that 'host' other elements, such as controls (see below). Please note that cDialog is a ready-to-use thing, you just have to provide its constructor with flags (there are about 40 bit masks for your convenience, so the whole thing is highly configurable).

Controls
This section groups standard controls found on many systems, such as cList (a list of selectable strings), cButton (a button with associated text and return value), cEdit (textual entry field), etc. These controls could be attached to the above described forms. Please note that cDialog is nothing else but a cCustomForm with several controls attached to it, according to the flags (its 'style') you pass to its constructor.

Built-in String Constants
String constants that are instantly usable from within your application or game.

Input and Output

File I/O
Structures of the File I/O section define the most basic file operations in the CyOS. Please look at Archive, FileInput, FileOutput and FileFind structures.

Keyboard Input
Some structures, functions and defines for work with keyboard. We recommend that you look at DirectKeyboard structure. It's more difficult, but it's a more effective way to handle keyboard input (the easy way is to just process respective Message's).

Serial Port Access
Functions for working with com port. Please see the respective Accessing Serial Port tutorials.

Formatted Output
With the help of these functions you can output data to either console or string buffer.

Utilities

String Manipulation
Some functions for string manipulations. Among these functions you can find ANSI C compatible ones (like strcpy(), strcmp() and others) as well as and functions specific to CyOS (is_pattern(), trunc_spaces(), strends()).

Conversion Routines
These functions are used to convert values from one format to another. Please make special note of cyid2str() and str2cyid(), because they can help to convert CyID to string and vice versa.

Integer Math
Here you can find some mathematical functions, imin() and imax() among them. If you need to find the minimal or maximal of two numbers, look at these efficient functions.

Vararg Functions
Some functions for handling variable numbers of arguments (like those in stdarg.h).

Miscellaneous
Structures and functions that don't fit anywhere else. By using Score structure methods, you make your game players' results available for upload to the Cybiko site. Thus, your game becomes contest-enabled!


Alphabetical index

Alphabetical List

a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | y | z

A

AppGeneric | The base structure for applications
Archive | Archive storage. A file that holds more files inside, each one of may be compressed
AppGeneric_cancel_shutup | Cancels the MSG_SHUTUP message
AppGeneric_clear_screen | Clears the screen with a white color
AppGeneric_ext_cancel_shutup | Cancels the MGS_SHUTUP message statically
AppGeneric_get_display | Retrieves DisplayGraphics object to access the Cybiko display
AppGeneric_get_message | Returns the message for the specified interval
AppGeneric_get_name | Retrieves the name of the application
AppGeneric_has_focus | Tests whether the process has the device's focus
AppGeneric_init_display | Obtains the graphics context
AppGeneric_pause | Pauses execution of the application
AppGeneric_peek_message | Peeks or gets a message from the queue
AppGeneric_proc | Provides generic message processing
AppGeneric_put_message | Puts a Message in the application's Queue
AppGeneric_request_focus | Requests that the application receive the focus
archive | A pointer to the module's Archive object
Archive_archive_name | Returns the archive name
Archive_count_entries | Returns the number of entries (resources) in the archive
Archive_ctor | Initializes an Archive object for a specified archive file
Archive_dtor | Destructor of an Archive object
Archive_get_name | Retrieves the name of the Nth entry
Archive_is_good | Checks whether the Archive object is valid
Archive_open | Opens an Input for the specified resource index
Archive_open_Ex | Opens an Input from the archive for the file named
Archive_open_write | All files in the archive are numbered
Archive_open_write_Ex | Opens an Output for the archive file named
ARROW_DOWN | Arrow down
ARROW_UP | Arrow up
atoul | Converts ASCII decimal into long

B

Bitmap | A structure for creating and working with simple bitmapped objects
BitmapSequence | While the Bitmap structure is used for working with a single bitmap, the BitmapSequence is used for working with a Bitmap array
bitset | Works with a set of bits using simple bit operations
Buffer | A dynamic memory buffer
baud_rate | Placeholder for COMM_BAUD_* values
Bitmap_clear | Fills whole bitmap by white color
Bitmap_ctor | The simple Bitmap constructor
Bitmap_ctor_Ex1 | The first extended version of the Bitmap_ctor function
Bitmap_ctor_Ex2 | The second extended version of the Bitmap_ctor function
Bitmap_ctor_Ex3 | The third extended version of the Bitmap_ctor function
Bitmap_dtor | Destructor
Bitmap_fill | Fills whole bitmap by a color pointed on the color_t value
Bitmap_get_h | Returns physical height of the Bitmap (in pixels)
Bitmap_get_w | Returns physical width of the Bitmap (in pixels)
Bitmap_load | Loads bitmap from an opened stream
Bitmap_store | Stores bitmap to an opened stream
BitmapSequence_ctor | Simple BitmapSequence constructor
BitmapSequence_ctor_Ex | This is the extended version of the BitmapSequence_ctor function
BitmapSequence_dtor | Destructor
BitmapSequence_get_bitmap | Returns a pointer on the Bitmap object that has the 'bitmap_index' index
BitmapSequence_get_size | Returns the number of bitmaps in a BitmapSequence object
BitmapSequence_load | Loads the bitmap sequence from an opened stream
BitmapSequence_store | Stores a bitmap sequence to an opened stream
bitset_add | Adds two bitsets, the same as logical OR
bitset_clear | Sets all bits to zero
bitset_ctor | Creates a set of bits
bitset_dtor | The bitset destructor
bitset_excl | Excludes a bit from the set at a specified position
bitset_in | Determines whether the bit at a specified position was excluded
bitset_incl | Adds the bit at a specified position to the set
bitset_mul | Multiplies two bitsets, the same as logical AND
bitset_sub | Subtracts two bitsets, the same as logical XOR
Buffer_compact | Resizes storage to the current data size
Buffer_ctor | Create an empty buffer of a specified data_size
Buffer_ctor_Ex | Creates a copy of the existing buffer
Buffer_dtor | Unlocks and frees a previously locked buffer
Buffer_ensure_size | Reallocates and copies the buffer's contents, if needed
Buffer_free | Clears the buffer and frees its storage
Buffer_get_allocated_size | Returns the size of the allocated space (current capacity that may be bigger than Buffer_get_size())
Buffer_get_char | Reads char at the specified 'offset'
Buffer_get_int | Reads the int value at the specified 'offset'
Buffer_get_long | Reads the long value at the specified 'offset'
Buffer_get_size | Returns the size of the data in the buffer
Buffer_is_locked | Returns lock state (locked or unlocked)
Buffer_load | Loads 'length' bytes from the Buffer, starting at the specified 'offset'
Buffer_load_string | Loads null terminated string
Buffer_lock | Locks storage and returns the pointer to it's area
Buffer_set_char | Writes char value 'data' at the specified 'offset'
Buffer_set_int | Writes the int 'data' at the specified 'offset'
Buffer_set_long | Writes the long value 'data' at the specified 'offset'
Buffer_set_size | Sets the size
Buffer_store | Stores some data at the specified offset
Buffer_store_string | Stores a null-terminated string into the buffer
Buffer_unlock | Unlocks the buffer's storage
beep | Produces a beep tone
BEEP_ERROR | The beep function argument for the ERROR dialog
BEEP_INFO | The beep function argument for the INFO dialog
BEEP_OK | The beep function argument for the OK dialog
BEEP_QUESTION | The beep function argument for the QUESTION dialog
BM_FLIP_X | Invert x coordinate
BM_FLIP_Y | Invert y coordinate
BM_INVERSE | Invert colors
BM_NORMAL | Keep as is

C

cBevel | CBevel object is an outlined empty rectangle
cBitmap | Use this structure to place a simple picture on the screen
cBox | CBox is simply a filled rectangle
cButton | A basic button
cClip | This is a base window structure - a clipped box, which may contain other objects
cCustomForm | This is a structure of the main form
cDialog | The structure for common dialogs
cEdit | This structure puts a standard edit control on the Cybiko screen
cEngine | Provides timely graphical output
cFrameForm | This structure creates a full-screen, framed window
cItem | This structure implements methods for working with simple units of the list, such as a text string
cList | This structure implements methods for working with a list and a menu
cObject | Represents a simple graphic object, and implements base message-delivery and command-processing functions
COMMConfig | COM port configuration parameters COM port configuration parameters
cProgressBar | Adds a progress bar to your application
cSItem | A cSItem object might have an icon on the left and/or additional text on the right
cText | Static, transparent text line
cWinApp | The cWinApp structure is your application object
cXByte | A framed string with an icon on the left
cXItem | The same type of string as in the cItem structure
cXStr | A cXStr object might have an icon on the left and/or additional text on the right
cyfolk_t | Describes a person on the Finder's list
cBevel_ctor | Constructor
cBevel_Disable | Disables the cBevel object so that it cannot be selected
cBevel_Disconnect | Disconnects cBevel from its parent object
cBevel_dtor | Destructor
cBevel_Enable | Enables the cBevel object so that it may be selected
cBevel_GetParent | Returns a pointer to the parent object's cClip
cBevel_Hide | Hides the cBevel object
cBevel_proc | The Message-processing function
cBevel_Select | Selects cBevel object
cBevel_Show | Shows the cBevel object
cBevel_update | Updates a cBevel object
cBitmap_ctor | Constructor for a non-transparent picture
cBitmap_ctor_Ex | Extended version of the cBitmap_ctor function
cBitmap_Disable | Disables a cBitmap object so that it cannot be selected
cBitmap_Disconnect | Disconnects a cBitmap from its parent object
cBitmap_dtor | Destructor
cBitmap_Enable | Enables a cBitmap object so that it may be selected
cBitmap_GetParent | Returns a pointer to the parent object's cClip
cBitmap_Hide | Hides a cBitmap object
cBitmap_proc | The Message-processing function
cBitmap_Select | Selects a cBitmap object
cBitmap_SetFlips | Changes the 'flip' state
cBitmap_Show | Shows a cBitmap object
cBitmap_update | Updates a cBitmap object
cBox_ctor | Constructor
cBox_Disable | Disables a cBox object so that it cannot be selected
cBox_Disconnect | Disconnects a cBox object from its parent object
cBox_dtor | Destructor
cBox_Enable | Enables a cBox object - so that it may be selected
cBox_GetParent | Returns a pointer to the parent object's cClip
cBox_Hide | Hides a cBox object
cBox_proc | The Message-processing function
cBox_Select | Selects a cBox object
cBox_Show | Shows a cBox object
cBox_update | Updates a cBox object
cButton_ctor | Initializes a cButton object
cButton_Disable | Disables the cButton object so that it cannot be selected.
cButton_Disconnect | Disconnects the cButton object from its parent object
cButton_dtor | Deletes a cButton object
cButton_Enable | Enables the cButton object so that it may be selected
cButton_GetModalResult | Returns the button modal result, which was set in the cButton constructor
cButton_GetParent | Returns a pointer to the parent object
cButton_Hide | Hides a cButton object
cButton_proc | The Message-processing function
cButton_Select | Selects a cButton object
cButton_Show | Shows cButton object
cButton_update | Updates a cButton object
cClip_AddObj | Adds the object 'obj' to the cClip in position (x,y)
cClip_Disable | Disables the cClip object so that it cannot be selected
cClip_Disconnect | Disconnects the cClip from its parent object
cClip_Enable | Enables the cClip object - so that it may be selected
cClip_FindObj | Returns the child object's index in the cClip
cClip_get_by_index | Returns an object with its index
cClip_GetCount | Returns the count of child objects
cClip_GetParent | Returns a pointer to the parent object's cClip
cClip_GetSelectedObject | Returns the currently selected object in the cClip
cClip_GetShiftx | Returns the 'x' coordinate shift (as a result of scrolling)
cClip_GetShifty | Returns the 'y' coordinate shift (as a result of scrolling)
cClip_Hide | Hides the cClip object
cClip_InsObj | Adds the object 'obj' to the cClip in position (x,y), with a z-position index (maximal index is on the top)
cClip_proc | Message-processing function
cClip_RemObj | Removes the object from cClip
cClip_Scroll | Scrolls the cClip to make a specified rectangle visible
cClip_Scroll_Ex | Scrolls the cClip by ( x, y ), but does not exceed the child's boundaries
cClip_Select | Selects the cClip object
cClip_SelectFirst | Selects the first object in the cClip
cClip_SelectNext | Selects the next object in the cClip
cClip_SelectPrev | Selects the previous object in the cClip
cClip_SendScroll | Forces this object to redraw its scrolling arrows
cClip_Show | Shows the cClip object
cClip_update | Updates a cClip object
cCustomForm_AddObj | Adds an object to the cCustomForm in position ( x, y )
cCustomForm_ctor | Constructor
cCustomForm_Disable | Disables the cCustomForm object so that it cannot be selected
cCustomForm_Disconnect | Disconnects a cCustomForm from its parent object
cCustomForm_dtor | Deletes a cCustomForm object
cCustomForm_Enable | Enables a cCustomForm object so that it may be selected
cCustomForm_FindObj | Returns the child object index in a cCustomForm (or -1 if the object was not found)
cCustomForm_get_by_index | Returns the object index
cCustomForm_GetCount | Returns the count of child objects
cCustomForm_GetParent | Returns a pointer to the parent object
cCustomForm_GetSelectedObject | Returns the currently selected object
cCustomForm_GetShiftx | Returns the 'x' coordinate shift (as a result of scrolling)
cCustomForm_GetShifty | Forces this object to redraw its scrolling arrows
cCustomForm_Hide | Hides a cCustomForm object
cCustomForm_InsObj | Adds an object to the cCustomForm in position ( x, y ) with a z-position 'index' (maximal index is on the top)
cCustomForm_proc | The message-processing function
cCustomForm_RemObj | Removes an object from a cCustomForm
cCustomForm_Scroll | Scrolls a cCustomForm to make a rectangle visible
cCustomForm_Scroll_Ex | Scrolls a cCustomForm by ( x, y ), but will not exceed the child's boundaries
cCustomForm_Select | Selects a cCustomForm object
cCustomForm_SelectFirst | Selects the first object in the cCustomForm
cCustomForm_SelectNext | Selects the next object in the cCustomForm
cCustomForm_SelectPrev | Selects the previous object in the cCustomForm
cCustomForm_SendScroll | Forces this object to redraw its scrolling arrows
cCustomForm_Show | Shows a cCustomForm object
cCustomForm_ShowModal | Shows a form in modal mode
cCustomForm_update | Updates a cCustomForm object
cDialog_AddObj | Adds an object to the cDialog in position (x, y)
cDialog_ctor | Initializes a cDialog object
cDialog_Disable | Disables cDialog object so that it cannot be selected
cDialog_Disconnect | Disconnects the cDialog from its parent object
cDialog_dtor | Destructor
cDialog_Enable | Enables the cDialog object so that it may be selected
cDialog_FindObj | Returns the child object index in the cDialog (or -1)
cDialog_get_by_index | Returns the object's index (or NULL)
cDialog_GetCount | Returns the count of child objects
cDialog_GetEditText | Copies an edit string from the internal buffer into "ptr_buffer"
cDialog_GetParent | Returns a pointer to the parent object
cDialog_GetSelectedObject | Returns the currently selected object
cDialog_GetShiftx | Returns the x coordinate shift (as a result of scrolling)
cDialog_GetShifty | Returns the y coordinate shift (as a result of scrolling)
cDialog_Hide | Hides the cDialog object
cDialog_InsObj | Adds an object to the cDialog in position (x, y) with a z-position index (maximal index is on the top)
cDialog_PlaySound | Plays the standard dialog sound
cDialog_proc | Message-processing function
cDialog_RemObj | Removes an object from the cDialog
cDialog_Scroll | Scrolls cDialog to make rectangle visible
cDialog_Scroll_Ex | Scrolls a cDialog by ( x, y ), but cannot exceed the child's boundaries
cDialog_Select | Selects a cDialog object
cDialog_SelectFirst | Selects the first object in the cDialog
cDialog_SelectNext | Selects the next object in the cDialog
cDialog_SelectPrev | Selects the previous object in the cDialog
cDialog_SendScroll | Forces this object to redraw its scrolling arrows
cDialog_SetEditText | Sets an initial string in an edit line
cDialog_Show | Shows a cDialog object
cDialog_ShowModal | Shows a cDialog in modal mode
cDialog_update | Updates a cDialog object
cEdit_AppendText | Appends text from external buffer
cEdit_ctor | Constructor
cEdit_Disable | Disables the cEdit object so that it cannot be selected
cEdit_Disconnect | Disconnects a cEdit from its parent object
cEdit_dtor | Destructor
cEdit_Enable | Enables a cEdit object so that it may be selected
cEdit_GetBufferPtr | Returns a pointer to the internal buffer
cEdit_GetCursorPos | Returns the current cursor position relative to the beginning of a piece of text
cEdit_GetParent | Returns a pointer to the cClip of the parent object
cEdit_GetText | Saves "text" to the external buffer
cEdit_GetText_Ex | Saves "text" to the external output stream
cEdit_GetTextLength | Returns the current text length (not including finishing '\0')
cEdit_Hide | Hides a cEdit object
cEdit_HighliteText | Sets a highlighted state
cEdit_IsHighlited | Highlighted state
cEdit_IsModified | Checks whether the text has been modified
cEdit_MoveCursor | Uses one of these defined methods for moving the cursor: one line up = mc_lineup; one line down = mc_linedown; one page up = mc_pageup; one page down = mc_pagedown (the number of lines per page is defined in page_line_count)
cEdit_proc | Message-processing function
cEdit_Select | Selects a cEdit object
cEdit_SetCursorPos | Moves the cursor to a given position relative to the beginning of a string or block of text
cEdit_SetPageLineCount | Sets the page length (number of lines to move text when using cursor pageup/down commands)
cEdit_SetReadOnly | Sets a read-only state
cEdit_SetText | Loads text from an external buffer
cEdit_SetText_Ex | Loads text from an external input stream
cEdit_Show | Shows a cEdit object
cEdit_update | Updates a cEdit object
cEngine_Lock | Locks a cEngine object
cEngine_Unlock | Unlocks a cEngine object
cf | Array of records describing the people in the vicinity
cf_fk | Additional information about the person listed
cf_id | Cy ID of the user's Cybiko device
cf_match | Mean match coefficient of person and device owner
cf_my_match | The mean match coefficient of the listed person - and the device's owner
cf_name_ind | Number of people with the same nickname in the Finder's list
cFrameForm_AddObj | Adds an object to the cFrameForm in position (x, y)
cFrameForm_ctor | Constructor
cFrameForm_Disable | Disables a cFrameForm object so that it cannot be selected
cFrameForm_Disconnect | Disconnects a cFrameForm from its parent object
cFrameForm_dtor | Deletes the cFrameForm object
cFrameForm_Enable | Enables a cFrameForm object so that it may be selected
cFrameForm_FindObj | Returns the child object's index in the cFrameForm (or -1 )
cFrameForm_get_by_index | Returns an object's index (or NULL)
cFrameForm_GetCount | Returns the count of child objects
cFrameForm_GetParent | Returns a pointer to the parent object
cFrameForm_GetSelectedObject | Returns the currently selected object
cFrameForm_GetShiftx | Returns the 'x' coordinate shift (as a result of scrolling)
cFrameForm_GetShifty | Returns the 'y' coordinate shift (as a result of scrolling)
cFrameForm_Hide | Hides a cFrameForm object
cFrameForm_InsObj | Adds an object to the cFrameForm in a position ( x, y ) with a z-position index (maximal index is on the top)
cFrameForm_proc | The Message-processing function
cFrameForm_RemObj | Removes an object from a cFrameForm
cFrameForm_Scroll | Scrolls a cFrameForm to make a rectangle visible
cFrameForm_Scroll_Ex | Scrolls a cFrameForm by (x, y), but cannot exceed the child's boundaries
cFrameForm_Select | Selects a cFrameForm object
cFrameForm_SelectFirst | Selects the first object in the cFrameForm
cFrameForm_SelectNext | Selects the next object in the cFrameForm
cFrameForm_SelectPrev | Selects the previous object in the cFrameForm
cFrameForm_SendScroll | Forces this object to redraw its scrolling arrows
cFrameForm_Show | Shows a cFrameForm object
cFrameForm_ShowModal | Shows a cFrameForm in modal mode
cFrameForm_update | Updates a cFrameForm object
ch | Character read from the keyboard
cItem_ctor | Constructor
cItem_Disable | Disables a cItem object so that it cannot be selected
cItem_Disconnect | Disconnects a cItem from its parent object
cItem_dtor | Destructor
cItem_Enable | Enables a cItem object so that it may be selected
cItem_GetParent | Returns a pointer to the parent object
cItem_GetTitle | Returns the item's title
cItem_Hide | Hides a cItem object
cItem_proc | Message-processing function
cItem_Select | Selects a cItem object
cItem_Show | Shows a cItem object
cItem_update | Updates a cItem object
ClientArea | The client area of the form
cList_AddItem | Adds an object (a cItem object for instance) to a cList object
cList_AddItem_Ex | The extended version of the cList_AddItem function
cList_AddObj | Adds an object to the cList in position (x, y)
cList_ctor | Constructor
cList_Disable | Disables a cList object so that it cannot be selected
cList_Disconnect | Disconnects a cList from its parent object
cList_dtor | Destructor
cList_Enable | Enables a cList object so that it may be selected
cList_FindObj | Returns a child object's index in the cList (or -1)
cList_get_by_index | Returns object index (or NULL)
cList_GetCount | Returns a count of child objects
cList_GetParent | Returns a pointer to the cClip of the parent object
cList_GetSelectedObject | Returns the currently selected object
cList_GetShiftx | Returns the 'x' coordinate shift (as a result of scrolling)
cList_GetShifty | Returns the 'y' coordinate shift (as a result of scrolling)
cList_Hide | Hides a cList object
cList_InsObj | Adds an object to the cList in position ( x, y ) with a z-position index (maximal index is on the top)
cList_proc | Message-processing function
cList_RemItem | Removes an object from a cList object
cList_RemObj | Removes an object from a cList
cList_Scroll | Scrolls a cList to make a rectangle visible
cList_Scroll_Ex | Scrolls a cList by (x, y), but cannot exceed the child's boundaries
cList_Sel | Returns the index of the currently selected object
cList_Select | Selects a cList object
cList_SelectFirst | Selects the first object in the cList
cList_SelectNext | Selects the next object in the cList
cList_SelectPrev | Selects the previous object in the cList
cList_SendScroll | Forces this object to redraw its scrolling arrows
cList_Show | Shows a cList object
cList_update | Updates a cList object
clock | Returns the time from the system startup in milliseconds; updated every 10 mS
cool_bold_font | Handle for the 'cool bold' font
cool_normal_font | Handle for the 'cool normal' font
cProgressBar_ctor | Constructor
cProgressBar_Disable | Disables a cProgressBar object so that it cannot be selected
cProgressBar_Disconnect | Disconnects a cProgressBar from it's parent object
cProgressBar_dtor | Destructor
cProgressBar_Enable | Enables for selection cProgressBar object
cProgressBar_GetParent | Returns a pointer to the cClip of the parent object
cProgressBar_Hide | Hides a cProgressBar object
cProgressBar_proc | The Message-processing function
cProgressBar_Select | Selects a cProgressBar object
cProgressBar_SetCurrentPos | Sets the current bar position and updates the object
cProgressBar_Show | Shows a cProgressBar object
cProgressBar_update | Updates a cProgressBar object
cSItem_ctor | Constructor
cSItem_Disable | Disables a cSItem object so that it cannot be selected
cSItem_Disconnect | Disconnects a cSItem from its parent object
cSItem_dtor | Destructor
cSItem_Enable | Enables a cSItem object so that it may be selected
cSItem_GetParent | Returns a pointer to the parent object
cSItem_GetTitle | Returns the item's title
cSItem_Hide | Hides a cSItem object
cSItem_proc | The Message-processing function
cSItem_Select | Selects a cSItem object
cSItem_Show | Shows a cSItem object
cSItem_update | Updates a cSItem object
cText_ctor | Initializes a cText object
cText_Disable | Disables a cText object so that it cannot be selected
cText_Disconnect | Disconnects a cText object from its parent object
cText_dtor | Deletes a cText object
cText_Enable | Enables a cText object so that it may be selected
cText_GetParent | Returns a pointer to the parent object
cText_Hide | Hides a cText object
cText_proc | The message-processing function
cText_Select | Selects a cText object
cText_SetText | Sets a new text line
cText_Show | Shows a cText object
cText_update | Updates a cText object
CurrApplication | Parent application
cWinApp_AddObj | Adds an object to the cWinApp in position (x, y)
cWinApp_cancel_shutup | Cancels the MSG_SHUTUP message
cWinApp_clear_screen | Clears the screen with the color white
cWinApp_defproc | The Message-processing function
cWinApp_Disable | Disables a cWinApp object so that it cannot be selected
cWinApp_Disconnect | Disconnects a cWinApp from its parent object
cWinApp_Enable | Enables a cWinApp object so that it may be selected
cWinApp_ext_cancel_shutup | Cancels the MGS_SHUTUP message statically
cWinApp_FindObj | Returns a child object's index in cWinApp (or -1)
cWinApp_get_by_index | Returns an object with its index
cWinApp_get_display | Returns the graphics context
cWinApp_get_message | The calling thread waits until the first message that fits the specified range appears in the queue
cWinApp_get_name | Returns the message queue's name
cWinApp_GetCount | Returns a count of child objects
cWinApp_GetParent | Returns a pointer to the parent object
cWinApp_GetSelectedObject | Returns the currently selected object
cWinApp_GetShiftx | Returns the 'x' coordinate shift (as a result of scrolling)
cWinApp_GetShifty | Returns the 'y' coordinate shift (as a result of scrolling)
cWinApp_has_focus | Checks whether the application has the focus
cWinApp_Hide | Hides a cWinApp object
cWinApp_init_display | Obtains the graphics context
cWinApp_InsObj | Adds an object to the cWinApp in position (x, y) with a z-position index (maximal index is on the top)
cWinApp_pause | Pauses execution of the thread
cWinApp_peek_message | Peeks or gets a message from queue
cWinApp_put_message | Puts a Message in the Queue
cWinApp_RemObj | Removes an object from cWinApp
cWinApp_request_focus | Requests focus for the application
cWinApp_Scroll | Scrolls a cWinApp to make a rectangle visible
cWinApp_Scroll_Ex | Scrolls a cWinApp by (x, y), but cannot exceed the child's boundaries
cWinApp_Select | Selects a cWinApp object
cWinApp_SelectFirst | Selects the first object in the cWinApp
cWinApp_SelectNext | Selects the next object in the cWinApp
cWinApp_SelectPrev | Selects the previous object in cWinApp
cWinApp_SendScroll | Forces this object to redraw its scrolling arrows
cWinApp_Show | Shows a cWinApp object
cWinApp_update | Updates a cWinApp object
cXByte_ctor | Constructor
cXByte_Disable | Disables the cXByte object so that it cannot be selected
cXByte_Disconnect | Disconnects a cXByte from its parent object
cXByte_dtor | Destructor
cXByte_Enable | Enables a cXByte object so that it may be selected
cXByte_Esc | Restores information
cXByte_GetParent | Returns a pointer to the parent object
cXByte_GetTitle | Returns the item's title
cXByte_Hide | Hides a cXByte object
cXByte_OK | Saves input information
cXByte_proc | The Message-processing function
cXByte_SaveStr | Saves a Str to an external string
cXByte_ScrollLR | Recalculates a StrBox
cXByte_Select | Selects a cXByte object
cXByte_SelLeft | Selects the section on the item's left side (only if the item has the focus)
cXByte_SelRight | Selects the section on the item's right side (only if the item has the focus)
cXByte_SetLeft | Changes the left side's value by 'index'
cXByte_SetRight | Changes the right side's value by 'index'
cXByte_SetStart | Highlightes the entire string on the item's right side and positions the cursor at its end (only when the section on the item's right side is selected)
cXByte_Show | Shows a cXByte object
cXByte_update | Updates a cXByte object
cXItem_ctor | Constructor
cXItem_Disable | Disables a cXItem object so that it cannot be selected
cXItem_Disconnect | Disconnects a cXItem from its parent object
cXItem_dtor | Destructor
cXItem_Enable | Enables a cXItem object so that it may be selected
cXItem_Esc | Deselects the left or right section of the item (if either was selected), and restores L/Rsel from L/Rprev
cXItem_GetParent | Returns a pointer to the cClip of the parent object
cXItem_GetTitle | Returns the item's title
cXItem_Hide | Hides a cXItem object
cXItem_OK | Deselects the left or right section of the item (if either was selected), and saves L/Rsel to L/Rprev
cXItem_proc | The Message-processing function
cXItem_Select | Selects cXItem object
cXItem_SelLeft | Selects the left-side section of the item (only if the item has focus)
cXItem_SelRight | Selects the right-side section of the item (only if the item has focus)
cXItem_SetLeft | Changes the left section's value by 'index'
cXItem_SetRight | Changes the right section's value by 'index'
cXItem_Show | Shows a cXItem object
cXItem_update | Updates a cXItem object
cXStr_ctor | Constructor
cXStr_Disable | Disables a cXStr object so that it cannot be selected
cXStr_Disconnect | Disconnects a cXStr from its parent object
cXStr_dtor | Destructor
cXStr_Enable | Enables a cXStr object so that it may be selected
cXStr_Esc | Clears an edited string and deselects the section on the item's right side(if it was selected)
cXStr_GetParent | Returns a pointer to the cClip of the parent object
cXStr_GetTitle | Returns the item's title
cXStr_Hide | Hides a cXStr object
cXStr_OK | Saves an edited string and deselects the section on the item's right side (if it was selected)
cXStr_proc | The Message-processing function
cXStr_SaveStr | Saves a Str to an external string
cXStr_Select | Selects a cXStr object
cXStr_SelLeft | Selects the section on the item's left side (only if the item has the focus)
cXStr_SelRight | Selects the section on the item's right side (only if the item has the focus)
cXStr_SetLeft | Changes the left section's value by 'index'
cXStr_SetRight | Changes right section's value by 'index'
cXStr_SetStart | Highlightes the entire whole right-side string, and positions the cursor at its end (only when the section on the item's right side is selected)
cXStr_Show | Shows a cXStr object
cXStr_update | Updates a cXStr object
cyid | Cy ID of the device on which the score was reached
cyid_from | Cy ID of the sender device
cyid_to | Cy ID of the target device
calloc | Allocates an array in memory, with elements initialized to 0
CK_BEEP | Normal click sound
CK_BEEP_SHORT | Short click sound
CK_NO | No click sound
click_kind_t | Keyboard click sound
clock_t | Stores time values: used by the clock() function
CLR_BLACK | Make the object black
CLR_DKGRAY | Make the object dark gray
CLR_LTGRAY | Make the object light gray
CLR_WHITE | Make the object white
color_t | Display color
com_close | Closes an opened serial port
com_dev_t | Available serial ports
com_flush | Flushes serial port I/O buffers
com_get_config | Retrieves current configuration of a serial port
com_get_DTR | Gets the serial port's current DTR state
com_get_RTS | Gets serial port's current RTS state
com_get_state | Retrieves current state of a serial port
com_open | Opens a serial port for read / write access
com_read | Reads a byte from a serial port
com_set_config | Sets the serial port's configuration
com_set_DTR | Sets serial port's DTR state
com_set_RTS | Sets serial port's RTS state
com_wait_for_data | Waits for data from a serial port
com_write | Writes a byte to a serial port
cprintf | Formats and prints the string to the Cybiko console
cy3d_cos | Calculates the cosine of the angle
cy3d_distance | Retrieves the distance between two points
cy3d_distance2 | Retrieves the square of the distance between the two points
cy3d_draw_background | Fills the top and bottom of the screen with the specified colors
cy3d_draw_map_buffer | Copies from the source video buffer to the destination video buffer performing bitwise OR
cy3d_draw_map_buffer_xor | Copies from the source video buffer to the destination video buffer performing bitwise XOR
cy3d_draw_sky | Fills the top part of the screen with the specified color
cy3d_draw_sprite | Draws a sprite in the specified position in the 3D world
cy3d_draw_tex_column | Draws a column of the texture
cy3d_draw_wall | Draws wall in the 3D world
cy3d_load | Loads the image collection with the specified name
cy3d_load_spr | Loads the sprite collection with the specified index in the application resource list
cy3d_load_tex | Loads the texture collection with the specified index in the application resource list
cy3d_mirror_buffer | Copies the top part of the screen to the bottom part of the screen
cy3d_move | Moves a point by a fixed distance in the specified direction
cy3d_point | Converts the point's coordinates from integer values to fixed point (8.8) values
cy3d_pos | Converts the point's coordinates, from fixed point (8.8) values to integer values
cy3d_sin | Calculates sine of the angle
cy3d_sqrt | Retrieves square root of the value
cy3d_warp | Transforms the point's position in the 3D world to its position in the camera's coordinate system (i.e
cyid2str | Converts CyID from cyid_t to text
cyid_t | Device's Cy ID
CYPETNAMESIZE | Maximum length of the Cypet name

D

DirectKeyboard | A DirectKeyboard object scans the CYBIKO keyboard to determine what keys the user has pressed
DisplayGraphics | This structure is designited to execute any draw operation on the cybiko display. This structure is designited to execute any draw operation on the Cybiko computer's display. If you want to make draw operations on a bitmap object, it's best to use the Graphics structure. The Cybiko computer features two displays; one of them virtual. We refer to these displays as 'graphics pages.' The draw operations are performed on the virtual graphics page, and then shown as the Cybiko screen's graphics page
data_bits | Placeholder for COMM_DATABITS_* values
day | Day of month, 1..31
deleted | TRUE if the Message has been deleted from the queue
DirectKeyboard_dtor | Deletes a DirectKeyboard object
DirectKeyboard_get_instance | Initializes a DirectKeyboard object
DirectKeyboard_is_key_pressed | Checks whether a specified key is being pressed
DirectKeyboard_scan | Scans the CYBIKO keyboard to determine what keys are being pressed
DisplayGraphics_draw_bitmap | Draws a bitmap 'bmp' in a specified position (left, top) in 'fm' mode
DisplayGraphics_draw_char | Draws a character 'fc' with the current font in a specified position (fx, fy)
DisplayGraphics_draw_hline | Draws a horizontal line from point (x , y) to point (xx , y)
DisplayGraphics_draw_line | Draws a solid line from point (x,y) to point (xx,yy)
DisplayGraphics_draw_rect | Draws a rectangular frame in the current color
DisplayGraphics_draw_rect_Ex | Duplicates the DisplayGraphics_draw_rect function
DisplayGraphics_draw_text | Draws text in a specified position (left, top) with the current font
DisplayGraphics_draw_text_Ex | Duplicates the DisplayGraphics_draw_text function
DisplayGraphics_draw_vline | Draws a vertical line from point (x, y) to point (x , yy)
DisplayGraphics_fill_rect | Fills a rectangle with the current color
DisplayGraphics_fill_rect_Ex | Duplicates the Graphics_fill_rect function
DisplayGraphics_fill_screen | Fills the screen with the 'fc' color
DisplayGraphics_flip | Switches background and foreground pages and shows the background screen on the LCD
DisplayGraphics_get_buf_addr | Returns a pointer to an image of the DisplayGraphics object destination
DisplayGraphics_get_bytes_total | Returns the number of bytes amount in the screen buffer
DisplayGraphics_get_char_height | Returns the current font's character's height
DisplayGraphics_get_char_width | Returns the current font's character width
DisplayGraphics_get_clip | Returns a clip region
DisplayGraphics_get_color | Returns the current foreground color
DisplayGraphics_get_draw_mode | Returns the current draw mode
DisplayGraphics_get_font | Returns the current font
DisplayGraphics_get_page | Returns the current graphics page number (0 or 1)
DisplayGraphics_get_page_ptr | Returns the pointer to the screen buffer for the 'fp' graphics page
DisplayGraphics_get_pixel | Returns the color of the pixel with coordinate (fx , fy)
DisplayGraphics_page_copy | Copies a rectangular area from one graphics page to another
DisplayGraphics_page_copy_Ex | Duplicates the DisplayGraphics_page_copy function
DisplayGraphics_put_background | Sets an image pointed by ptr_background as a background image
DisplayGraphics_scroll | Scrolls a rectangular area by dx and dy
DisplayGraphics_set_bitmap | Sets a bitmap 'bmp' as the destination for drawings
DisplayGraphics_set_bkcolor | Sets the current background color
DisplayGraphics_set_clip | Sets a clip region, defined by coordinates that are stored in fx, fy, fw and fh parameters
DisplayGraphics_set_clip_Ex | Duplicates the Graphics_set_clip function
DisplayGraphics_set_color | Sets the current foreground color
DisplayGraphics_set_draw_mode | Sets the current drawing mode
DisplayGraphics_set_font | Sets the font object as a current font
DisplayGraphics_set_page | Sets the page 'page' as a target for drawing, and in default sends it to the LCD
DisplayGraphics_set_pixel | Sets the color value 'fc' for pixel (fx, fy)
DisplayGraphics_show | Sends the current graphics page to the LCD
DisplayGraphics_show_Ex | The extended version of the DisplayGraphics_show function
DisplayGraphics_string_width | Returns the width (in pixels) of a string in the current font
DisplayGraphics_string_width_Ex | Returns the width (in pixels) of the first 'flen' symbols in a string
dst_name | The name of the target process
decrement_usage | Decrements the reference count for the current module
DEFAULT_DRIVE_NAME | Name of the default flash device
delivery_t | Message delivery state
disable_key_click | Disables the click sound for the keys specified, enables the click sound for the rest keys
DL_ABORT | Message delivery aborted by internal error or user request
DL_INQUEUE | Message is in queue to deliver; please, don't delete the message while in this state
DL_NONE | Message was created and possibly posted
DL_SUCCESS | Message was delivered successfully
DL_TIMEOUT | Message delivery finished by timeout
DL_WAIT | Message is being delivered
DM_OR | Make the image opaque; do not allow background color to show through the object
DM_PUT | Place the image as is
DM_XOR | XOR pixels overlay bitmap pixels
draw_bar | Fills a rectangle with a specified color, to form a color bar
draw_bounded_text | Draws bounded text with trailing dots if text is cut
draw_lib | Draws a bitmap in the specified position
draw_roundrect | Draws a custom rectangle with caption
drawmode_t | Drawing mode
DRIVE_A_NAME | Name of flash device A
DRIVE_B_NAME | Name of flash device B

E

enable_function_keys | Enables or disables function key processing
enable_sounds | Enables or disables tone generation
enable_sticking_keys | Enables or disables "sticking keys" option
enable_vibration | Enables or disables vibration
execute_module | Loads and executes the module, then waits for it's module_main to exits
exit | Exits current the thread with some code

F

File | The object to be manipulated
FileFind | File finder. Implements the functions needed to find a set of files
FileInput | The Input file stream
FileOutput | The Output file stream
Finder | Finder is a resident program; that is, it is always in memory. It's main purpose is to gather information about the Cy-environment
Flag | The flag synchronization object (aka Semaphore)
Flagex | Synchronization object that combines FLAG and MutEX (FLAGEX)
folk_t | Describes the " You&me/About Me " and " You&me/About You " information
Font | Provides functions for manipulating the appearance of text characters
f_age | Age
f_age_visible | Age visibility flag
f_gender | Gender
f_height | Height
f_height_visible | Height visibility flag
f_hobby1 | Hobby 1
f_hobby1_visible | Hobby 1 visibility flag
f_hobby2 | Hobby 2
f_hobby2_visible | Hobby 2 visibility flag
f_hobby3 | Hobby 3
f_hobby3_visible | Hobby 3 visibility flag
f_max_age | Maximal age of friend to seek
f_max_height | Maximal height of friend to seek
f_max_weight | Maximal weight of friend to seek
f_min_age | Minimal age of friend to seek
f_min_height | Minimal height of friend to seek
f_min_weight | Minimal weight of friend to seek
f_nick | Nickname
f_purpose | Purpose to find friend
f_purpose_visible | Purpose visibility flag
f_secret1 | Secret field 1
f_secret2 | Secret field 2
f_secret3 | Secret field 3
f_seek_age_degree | Importance of age of friend to seek(0 - 5)
f_seek_gender | Gender of friend to seek
f_seek_gender_degree | Importance of gender of friend to seek(0 - 5)
f_seek_height_degree | Importance of height of friend to seek(0 - 5)
f_seek_hobby1 | Hobby 1 of friend to seek
f_seek_hobby1_degree | Importance of hobby 1 of friend to seek(0 - 5)
f_seek_hobby2 | Hobby 2 of friend to seek
f_seek_hobby2_degree | Importance of hobby 2 of friend to seek(0 - 5)
f_seek_hobby3 | Hobby 3 of friend to seek
f_seek_hobby3_degree | Importance of hobby 3 of friend to seek(0 - 5)
f_seek_purpose | Purpose to find friend
f_seek_purpose_degree | Importance of purpose of friend to seek(0 - 5)
f_seek_secret1 | Secret field 1 of friend to seek
f_seek_secret1_degree | Importance of secret field 1 of friend to seek(0 - 5)
f_seek_secret2 | Secret field 2 of friend to seek
f_seek_secret2_degree | Importance of secret field 2 of friend to seek(0 - 5)
f_seek_secret3 | Secret field 3 of friend to seek
f_seek_secret3_degree | Importance of secret field 3 of friend to seek(0 - 5)
f_seek_weight_degree | Importance of weight of friend to seek(0 - 5)
f_weight | Weight
f_weight_visible | Weight visibility flag
File_bad_blocks_total | Returns the total number of bad blocks on the specified device
File_block_size | Returns the block size for the specified device
File_blocks_total | Returns the total number of blocks on the specified device
File_bootable | Returns TRUE if the specified device is bootable
File_bytes_total | Returns the total number of bytes on the specified device
File_ctor | Creates an empty File object
File_ctor_Ex | Extended version of the File_ctor function
File_dtor | Destructor
File_exists | Checks whether a file with specified name exists
File_files_total | Returns the total number of files on the specified device
File_free_blocks_total | Returns the number of free blocks on the specified device
File_free_bytes_total | Estimates the number of free bytes on the specified device
File_free_user_bytes_total | Estimates the number of free bytes for user data on the specified device
File_get_date | Returns the time the file was last modified
File_get_info | Initializes the File object's fields (name, date, length) of the File object, using the specified file's parameters
File_is_free | Checks whether a file is open for IO functions
File_is_valid_name | Returns TRUE if the specified string is valid as a filename
File_remove | Deletes the specified file if it is not being modified (written to or read)
File_rename | Renames the specified file if it is not being modified (written to or read)
File_set_date | Sets date the file was last modified
FileFind_ctor | Starts a new search session using a specified search mask
FileFind_dtor | Deletes an object
FileFind_has_more_elements | Checks wheter there are any elements left in the search
FileFind_init | Initializes the new file search session
FileFind_next_element | Retrieves the next element of the file search session
FileInput_ctor | Creates an empty input file stream object
FileInput_ctor_Ex | Creates an input file stream object for a file with the specified name
FileInput_dtor | Destructor
FileInput_get_flags | Returns the stream's current state
FileInput_get_size | Returns the stream size (if applicable)
FileInput_is_bad | Returns TRUE if the BAD flag is set (stream is bad)
FileInput_is_eof | Returns TRUE if the EOF flag is set (stream reached end-of-file)
FileInput_is_good | Returns TRUE if the BAD flag is not set (stream is good)
FileInput_open | Opens an input stream for the file with the specified name
FileInput_read | Reads a specified number of bytes from the stream
FileInput_read_byte | Reads the next byte from the stream
FileInput_seek | Seeks to the specified position, then returns the sought position
FileInput_seekg | Seeks an input stream
FileInput_tell | Returns the stream's current position
FileInput_tellg | Returns the stream's position
FileOutput_ctor | Creates an empty output file stream object
FileOutput_ctor_Ex | Creates an output file stream object for the file with the specified name
FileOutput_dtor | Destructor
FileOutput_get_flags | Returns the stream's current state
FileOutput_get_size | Returns the stream size (if applicable)
FileOutput_is_bad | Returns TRUE if the BAD flag is set (stream is bad)
FileOutput_is_eof | Returns TRUE if the EOF flag is set (stream reached end-of-file)
FileOutput_is_good | Returns TRUE if the BAD flag is not set (stream is good)
FileOutput_open | Opens an output stream for the file with the specified name
FileOutput_seek | Seeks to the specified position, then returns the sought position
FileOutput_seekp | Seeks an output stream
FileOutput_tell | Returns the stream's position
FileOutput_tellp | Returns the stream's position
FileOutput_truncate | Truncates a file associated with the stream
FileOutput_write | Writes the specified number of bytes to the stream
FileOutput_write_byte | Writes a byte to the stream
finder | Global Finder object
Finder_age | Calculates the user's age from his/her last birthday
Finder_create_name | Alters a real name to create a visible name form
Finder_find_active | Finds the active person's position in finder.cf array
Finder_find_disap | Finds the position in the finder.cf array of the person who temporarily disappeared from the finder's environment
Finder_find_unknown | Finds the position of the unknown person in the finder.cf array
Finder_get_best_ids | Gets the Cy IDs of the devices with the best match coefficient
finder_mutex | Mutually exclusive access synchronization object
Flag_clear | Sets a flag in a clear state, or changes the flag's state to clear
Flag_ctor | Creates a named flag
Flag_dtor | Destructor
Flag_flip | Flips a flag's state from set to clear or vice-versa
Flag_is_set | Returns TRUE if a flag is in the set state
Flag_set | Sets a flag, or changes the flag to the set state
Flag_set_Ex | Sets the flag to a specified state, or changes the flag's state to set or clear
Flag_wait | Waits for a specified state
Flag_wait_clear | Waits for the flag's state to become clear
Flag_wait_set | Wait the flag's state to change to set
Flagex_ctor | Constructs a named Flagex object
Flagex_dtor | Destructor
Flagex_is_locked | Checks whether Mutex is locked
Flagex_lock | Returns a lock
Flagex_notify | Notifies all waiting threads
Flagex_unlock | Unlocks Flagex
Flagex_wait | Waits for notification
flow_control | Placeholder for COMM_FC_* values
Font_bmp_by_char | Returns the bitmap object of the 'chr' character
Font_ctor | A simple Font constructor
Font_ctor_Ex | The extended version of the Font_ctor function
Font_dtor | Destructor
Font_get_bitmap | Returns a pointer to the bitmap with a specified index
Font_get_char_height | Returns the character's height in pixels
Font_get_char_width | Returns the character's width in pixels
Font_get_name | Returns the font name
Font_get_size | Returns the number of bitmaps in a font object
Font_get_spacing | Returns the font spacing value
Font_get_x | Returns the X origin of the Nth bitmap in a font object
Font_get_y | Returns the Y origin of the Nth bitmap in a font object
Font_is_fixed | Determines if the font is fixed
Font_load | Loads the font from an opened stream
Font_set_fixed | Sets or doesn't set a fixed font
Font_set_name | Sets the font name manually
Font_set_spacing | Sets the font spacing value
Font_split_string | Splits string str to substrings that fit specified width
Font_store | Stores a font object to an opened stream
Font_string_width | Returns the string's width in pixels
Font_string_width_Ex | The extended version of the Font_string_width function
FormNameString | Form caption
FC_CHANGED | File was changed
FC_FORMATTED | Disk was formatted
FC_RENAMED | File was renamed
fixed_t | Values with the fixed point ( 8.8 )
Flags | Stream's state flags
free | Frees a memory block
FREE_MEMORY | Frees the memory block allocated for the object (used in destructor)
FS_CREATED | File was created
FS_NONE | State is undefined
FS_REMOVED | File was removed

G

Graphics | This structure allows draw operations to be applied to Bitmap objects
get_trusted_time | Returns trusted time
Graphics_ctor | Simple Graphics constructor
Graphics_ctor_Ex | The extended version of the Graphics_ctor function
Graphics_draw_bitmap | Allows the bitmap 'bmp' to be drawn in a specified position (left, top) in 'fm' mode
Graphics_draw_char | Allows the character 'fc' to be drawn in the current font in specified position (x, y)
Graphics_draw_hline | Draws a horizontal line from point (x , y) to point (xx , y)
Graphics_draw_line | Draws a solid line from point ( x , y ) to point ( xx , yy )
Graphics_draw_rect | Draws a rectangular frame in the current color
Graphics_draw_rect_Ex | Duplicates the Graphics_draw_rect function
Graphics_draw_text | Allows 'text' to be drawn in the current font, in the specified position (left , top)
Graphics_draw_text_Ex | Duplicates the Graphics_draw_text function
Graphics_draw_vline | Draws a vertical line from point (x , y) to point (x , yy)
Graphics_dtor | Deletes a Graphics object
Graphics_fill_rect | Fills a rectangle with the current color
Graphics_fill_rect_Ex | Duplicates the Graphics_fill_rect function
Graphics_fill_screen | Fills the screen with the 'fc' color
Graphics_get_bitmap | Returns the current Bitmap context for drawing
Graphics_get_buf_addr | Returns a pointer to the Graphics object's associated image
Graphics_get_bytes_total | Returns the total number of bytes in the screen buffer
Graphics_get_char_height | Returns the current font's height
Graphics_get_char_width | Returns the current font's character width
Graphics_get_clip | Returns a clip region
Graphics_get_color | Returns the current foreground color
Graphics_get_draw_mode | Returns the current draw mode
Graphics_get_font | Returns the current font
Graphics_get_pixel | Returns the color of the pixel with coordinate ( fx , fy )
Graphics_put_background | Treats fp as a pointer to a background image and sends the image to its destination
Graphics_scroll | Scrolls a rectangle area that is defined by delta x, delta y in 'ptr_rectangle'
Graphics_set_bitmap | Sets a bitmap 'bmp' as the destination for drawings
Graphics_set_bkcolor | Sets the current background color by calling TGraph_set_bkcolor
Graphics_set_clip | Sets a clip region, defined by the coordinates stored in the fx, fy, fw, and fh parameters
Graphics_set_clip_Ex | Duplicates the Graphics_set_clip function
Graphics_set_color | Sets the current foreground color
Graphics_set_draw_mode | Sets the current draw mode
Graphics_set_font | Sets the current font
Graphics_set_pixel | The color, defined by the 'fc' parameter
Graphics_string_width | Returns the width (in pixels) of a string 'str' for the current font
Graphics_string_width_Ex | The extended version of the Graphics_string_width function
get_appchannel | Returns the current application's channel
get_appchannel_of | Returns the current application channel of the specified device
get_click_kind | Returns current kind of click sound
get_clicks_enabled | Returns state of a key clicks prohibition
get_communications | Returns the communications state
get_critical_mode | Returns the critical mode state
get_group_size | Returns the number of channels in a specified group
get_groupchannel | Returns the application channel, by channel group index
get_hardware_version | Returns the version of CYBIKO hardware
get_own_id | Returns device's CyID
get_people_around | Returns the CyID of the next device after prev_device (the CyIDs of people in the vicinity)
get_people_on_channel | Returns the device count on the channel
get_safety_pool_size | Returns safety pool size
get_sounds_enabled | Returns a sounds-enabled flag state

H

h | Rectangle's height
HelpContext | Window help context
hour | Hour, 0..23
howboys_around | Number of boys around
howmany_around | Number of people around
howmany_disap | Number of people around who temporarily disappeared from the finder's environment
howmany_unknown | Number of people around whose nicknames are "unknown"
hundreds | Hundredths of a second, 0..99
has_focus | Tests whether the current process has the focus
howmany_around_desktop | Returns the number of other users in the vicinity, with maximum activity
htoul | Converts hexadecimal ASCII into long

I

info_t | Describes the " You&me/Business Card " information
Input | An abstract object for sequential data access objects
i_addr | Address
i_addr_visible | Address visibility flag
i_bday | Birthday, day of the month
i_bmonth | Birthday, month
i_byear | Birthday, year
i_first_name | Real first name
i_first_name_visible | First name visibility flag
i_last_name | Real last name
i_last_name_visible | Last name visibility flag
i_mail | E-mail address
i_mail_visible | E-mail address visibility flag
i_other | Other contacts
i_other_visible | Other contacts visibility flag
i_phone | Phone number
i_phone_visible | Phone number visibility flag
Input_dtor | Destructor
Input_get_flags | Returns the current flags
Input_get_size | Returns the stream size (if applicable)
Input_is_bad | Returns TRUE if the BAD flag is set (stream is bad)
Input_is_eof | Returns TRUE if the EOF flag is set (stream reached end-of-file)
Input_is_good | Returns TRUE if the BAD flag is not set (stream is good)
Input_read | Reads the 'length' bytes from the stream
Input_read_byte | Reads the next byte from the stream
Input_read_dword | Reads a 32-bit word, independent of hardware
Input_read_word | Reads a 16-bit word, independent of hardware
Input_seekg | Seeks an input stream
Input_tellg | Returns the stream's position
imax | Returns the maximum of the two values
imin | Returns the minimum of the two values
in_rect | Returns TRUE if the point is in the rectangle area
increment_usage | Increments the reference count for the current module
init_module | Module initializer
invite_mode_t | Modes of invitation
is_low_memory | Returns low memory alarm
is_pattern | Checks whether string contains '*' or '?' characters
is_rf_paused | Returns TRUE if RF communications are paused
is_sticking_keys_enabled | Returns TRUE if "sticking keys" option is enabled
is_tone_playing | Allows the device to determine whether or not a tone is being played

J

K

KeyParam | The parameter holder for keyboard messages
KEY_0 | 0 key
KEY_1 | 1 key
KEY_2 | 2 key
KEY_3 | 3 key
KEY_4 | 4 key
KEY_5 | 5 key
KEY_6 | 6 key
KEY_7 | 7 key
KEY_8 | 8 key
KEY_9 | 9 key
KEY_A | A key
KEY_B | B key
KEY_BACKQUOTE | ` key
KEY_BACKSLASH | \ key
KEY_BACKSPACE | Backspace, move left and delete
KEY_C | C key
KEY_CLOSE_SBRACKET | ] key
KEY_COMMA | , key
KEY_CONTROL | Ctrl ( "alternative function" ) key
KEY_CY | CY sign (Fn+C)
KEY_D | D key
KEY_DEL | Delete/No, 2-nd big key
KEY_DOWN | Down ( joystick, arrow key )
KEY_E | E key
KEY_ENTER | Enter, 5-th big key
KEY_EQUAL | = key
KEY_ESC | Escape/Backspace ( upper left corner )
KEY_F | F key
KEY_G | G key
KEY_H | H key
KEY_HELP | Help key, in the upper-left corner of the case
KEY_I | I key
KEY_INS | Insert/Yes, 1-st big key
KEY_J | J key
KEY_K | K key
KEY_L | L key
KEY_LEFT | Left ( joystick, arrow key )
KEY_M | M key
KEY_MINUS | "-" key
KEY_N | N key
KEY_O | O key
KEY_OPEN_SBRACKET | [ key
KEY_P | P key
KEY_PERIOD | "." key
KEY_Q | Q key
KEY_QUOTE | ' key
KEY_R | R key
KEY_RIGHT | Right ( joystick, arrow key )
KEY_S | S key
KEY_SECTION1 | Hot key for section Main Menu
KEY_SECTION2 | Hot key for section Chat
KEY_SECTION3 | Hot key for section People
KEY_SECTION4 | Hot key for section Applications
KEY_SECTION5 | Hot key for section Games
KEY_SECTION6 | Hot key for section Labyrinth
KEY_SECTION7 | Hot key for section CyLandia
KEY_SELECT | Select, 4-th big key
KEY_SEMICOLON | ; key
KEY_SHIFT | Shift ( "upper case" ) key
KEY_SLASH | / key
KEY_SPACE | Space key
KEY_T | T key
KEY_TAB | Tab/Switch, 3-rd big key
KEY_U | U key
KEY_UP | Up ( joystick, arrow key )
KEY_V | V key
KEY_W | W key
KEY_X | X key
KEY_Y | Y key
KEY_Z | Z key
keymask_t | Keyboard modificators masks

L

last_key_time | Returns the time (in the time_t format) of the last keystroke
last_rf_clock | Returns the clock_t value of the last sent or received frame except sent pings (last RF activity clock)
last_rf_time | Returns the time the last frame was sent or received, except sent pings
LEAVE_MEMORY | Doesn't free the memory block allocated for the object (used in destructor)

M

Message | Structure for interprocess communications; can be sent either locally or remotely
Module | The CyOS Module
module_t | The application module structure
MSequence | The music sequence object
Mutex | Mutex a kind of a synchronization object that provides MUTually EXclusive (MUTEX) access to some part of the code (in some systems this is also known as Resource)
m_gfx | Pointer to graphics device context
m_process | Pointer to the current cywin application
mask | Keyboard modifier mask
Message_attach_buffer | Attaches a buffer to the message
Message_check_delivery | Checks the delivery state
Message_copy | Makes the destination Message an exact copy of the source Message
Message_delete | Deletes a message
Message_deliver | Delivers a message to a specified target, with delivery result notification
Message_get_buffer | Gets a pointer to the attached buffer
Message_get_key_param | Returns a pointer to the message's KeyParam structure
Message_get_sender_id | Returns the 32-bit device ID (CyID) of the Message's sender
Message_has_buffer | Tests whether the Message has an attached buffer
Message_is_broadcast | Determines if the message has no specific address
Message_new | Returns a new Message from the system stores
Message_post | Posts a message to a specified target
Message_post_all | Posts a message to all Queues
Message_wait_delivery | Waits until Message delivery is completed or flag is set
mf | The user's own profile
mi | The user's own business card
mini_bold_font | Handle for the 'mini bold' font
mini_normal_font | Handle for the 'mini normal' font
minute | Minute, 0..59
ModalResult | Result of form or dialog
modification_time | Time of the last modification
module | Pointer to the module to which the thread belongs
month | Month, 1..12
MSequence_ctor | Creates a music sequence from a specified resource (file) name
MSequence_dtor | Destructor
MSequence_get_curr_pos | Returns the current position (0xFFFF if it's about to start playing the first event)
MSequence_global_mute | Sets or clears the global mute flag
MSequence_is_playing | Checks whether a music sequence is playing
MSequence_is_sane | Checks whether the current content appears to be valid
MSequence_load | Loads a sequence from a specified Input stream
MSequence_mute_background | Sets or clears the background music(effects) mute flag
MSequence_mute_foreground | Sets or clears the foreground music(effects) mute flag
MSequence_play | Plays a music sequence in the foreground
MSequence_play_background | Plays the a music sequence in the background
MSequence_stop | Stops playing a music sequence
msgid | ID of the Message
Mutex_ctor | Constructs the named Mutex object
Mutex_dtor | Destructor
Mutex_is_locked | Checks whether the Mutex is locked
Mutex_lock | Returns a lock
Mutex_unlock | Unlocks a Mutex object
malloc | Allocates memory blocks
MAX_NAME_LEN | Maximum filename length
memcmp | Compares characters in two buffers
memcpy | Copies characters between buffers
memmove | Moves one buffer to another
memory_dump | Trace memory dump
memset | Sets buffers to a specified character
mFileName_current_device_name | Retrieves the name of the current flash device
mFileName_get_path | Retrieves the path to the file from the absolute file name
mFileName_is_valid_file_name | Verifies that the file name is valid
mFileName_make_path | Creates an absolute file name by combining the file name with the device name
mFileName_max_file_name_length | Retrieves the maximum file name length
mFileName_split_path | Splits the absolute file name into device name and file name
modulestate_t | The result of the module's execution
MP3_DRIVE_NAME | Name of MP3 player device
MSG_AUTODELETE | Message_deliver() flag, which deletes the message after it was delivered
MSG_CHARTYPED | Sends the message to the focused program when the user releases a key
MSG_DEVICE | Receiver sends the message when a device appears or disappears on the channel
MSG_FILES | Lists changes in the file system
MSG_GOTFOCUS | The process gets the message once it gets the focus
MSG_KEYDOWN | Sends the message to the focused program when the user presses a key
MSG_KEYMIN | Minimum ID of a keyboard message
MSG_KEYUP | Sends the message to the focused program when the user releases a key
MSG_LAUNCH | Sends the message to the Process you want to launch
MSG_LOSTFOCUS | The Process gets the message when it loses focus
MSG_MAX_TIMEOUT | Message_deliver() maximum timeout
MSG_PAINT | About repaint
MSG_PING | Message is sent by the Receiver to ping the listener process
MSG_POWERDOWN | Batteries are low, warn the user !
MSG_QUIT | Sends this message when the process should finish
MSG_SHUTUP | Process must be terminated
MSG_TIMER | Sent when the pre-set timer counts down to 0
MSG_USER | Start of the user_defined message ID
MSG_USER_FOLK | ID of the message sent to the application when any device appears or disappears from the environment

N

nfolk_t | Additional information about a person in Finder's list
name | File name
next | Pointer to the next Message in the queue
nickname | Cy name of the player, who reach the high score
NAMESIZE | Maximum length of the name
NICKNAMESIZE | Maximum length of the nickname
NOT_FOUND | Person with the specified parameter not found

O

Output | An abstract object for the sequential data access objects
Output_dtor | Destructor
Output_get_flags | Returns the current flags
Output_get_size | Returns the stream size (if applicable)
Output_is_bad | Returns TRUE if the BAD flag is set (stream is bad)
Output_is_eof | Returns TRUE if the EOF flag is set (stream reached end-of-file)
Output_is_good | Returns TRUE if the BAD flag is not set (stream is good)
Output_seekp | Seeks an output stream
Output_tellp | Returns the stream's position
Output_write | Writes the 'length' bytes to the stream
Output_write_byte | Writes a byte to the stream
Output_write_dword | Writes a 32-bit word, independent of hardware
Output_write_word | Writes a 16-bit word, independent of hardware
open_resource | Returns the resource from the current archive, using resource index
open_resource_Ex | Returns the resource from the current archive, using the resource name
own_icq | ICQ number of the device owner
own_icq_visible | ICQ number visibility flag

P

point_t | A point on a plane, with the coordinates represented by fixed point (8.8) values
pos_t | A point on a plane, with the coordinates represented by integer values
Process | A kind of thread that can process messages
p_x | X-coordinate of the point
p_y | Y-coordinate of the point
param | Additional parameters for the Message
parity_type | Placeholder for COMM_PARITY_* values
Process_get_display | Retrieves a DisplayGraphics object to the access display
Process_get_message | Returns the message after the specified interval
Process_get_name | Retrieves the Process' name
Process_has_focus | Tests whether the Process has the focus
Process_pause | Pauses execution of the Process
Process_peek_message | Peeks or gets message from the queue
Process_put_message | Puts a Message in the Process' Queue
Process_request_focus | Asks the system to activate the Process (pass the focus)
ps_x | X-coordinate of the point
ps_y | Y-coordinate of the point
play_raw | Starts playing a tone
play_tone | Starts tone generation
PR_IDLE | Very low priority (for background tasks)
PR_NORMAL | Normal (medium) priority
PR_RUNTIME | Very high priority (for runtime threads)
priority_t | The thread priority

Q

Queue | Messages queue; messages are stored in the queue
Queue_get_message | Returns the message from the specified interval
Queue_peek_message | Peeks at or gets a message from the queue
Queue_put_message | Puts a Message in the Queue
qflag_t | Enumeration of masks for local broadcast messages

R

raster_t | A collection of sprites or textures used by the CyOS 3D library
rect_t | A rectangle
r_data | Data for the images
r_num | Number of images in the collection
r_size | Size of a single image in the collection
rect_and | Intersects two rectangles
rect_or | Merges two rectangles
rect_set | Initializes a rectangle
reserved | Reserved
random | Returns a pseudo-random value from 0 to max - 1
realloc | Reallocates memory blocks
rect | Draws a rectangle with the specified color
RF_GROUP_APPS | Applications channel group
RF_GROUP_CHAT | Chat channel group
RF_GROUP_CYLAND | CyLandia channel group
RF_GROUP_DEFAULT | Default group for unknown applications
RF_GROUP_FILES | Files channel group
RF_GROUP_GAMES | Games channel group
RF_GROUP_LABYRINTH | Labyrinth channel group
RF_GROUP_OTHER | Reserved channel group
RF_GROUP_SERVER | Server channel group
RF_GROUP_SYSTEM | System channel group (for debugging purposes)
rf_pause | Pauses RF communications
rf_resume | Resumes RF communications after a pause

S

Score | The game's high score archive
score_t | The game's high score structure
SystemThread | Base object for all execution units (threads)
scancode | Keyboard virtual keys code
score | High score
Score_ctor | High score archive constructor
Score_dtor | High score archive destructor
Score_get_record_count | Returns the number of records in the high score archive
Score_is_valid | Checks the validity of the high score archive
Score_read | Reads the record from the high score archive
Score_write | Writes the record to the high score archive
Score_write_Ex | Writes the record to the high score archive
Screen | Global CyWin cEngine object
sDown | Enable scrolling down
second | Second, 0..59
size | File size
sNone | No scrolling available
stop_bits | Placeholder for COMM_STOPBITS_* values
sUp | Enable scrolling up
sUpDown | Enable scrolling both up and down
SystemThread_get_priority | Returns a thread's priority
SystemThread_pause | Pauses execution of the thread
SystemThread_set_priority | Changes the thread's priority
SCREEN_HEIGHT | CYBIKO screen height
SCREEN_WIDTH | CYBIKO screen width
SEEK_CUR | Seek from the current position (a positive offset indicates towards end of file)
SEEK_END | Seek from the end
SEEK_SET | Seek to the absolute position
seek_t | Defines the initial position in the stream and must be one of the following: SEEK_SET, SEEK_CUR or SEEK_END
select_app_partner | Invites a partner to launch a specified application
select_game_partner | Select a partner for single or multi-player games
select_partner | Selects a partner
select_partner_Ex | Extended version of the select_partner function
send_copy_msg | Sends a pre-written message to another application in the same Cybiko computer
send_msg | Sends a message to another application in the same Cybiko computer
send_msg_launch | Launches the 'app_name' application
send_remote_copy_msg | Sends pre-written message to another application in the same or other Cybiko computer
send_remote_msg | Sends message to another application in the same or another Cybiko computer
set_appchannel | Sets current application channel
set_best_appchannel | Selects the application channel with the last traffic
set_click_kind | Sets current kind of click sound
set_clicks_enabled | Disables or enables keyboard clicks
set_communications | Enables or disables communications through RF
set_critical_mode | Sets a special critical mode to disable network or internal task interrupts, such as invite
set_groupchannel | Selects the application channel by channel group index
set_hourglass | When you start this function, the system starts a special Thread to show the picture, which can eat up to 10-11% of processor time; after you stop it, don't forget to remove it from the screen by repainting it
size_t | Result of the sizeof operator
skipws | Skips white spaces
sleep | Pauses execution of the current thread
sprintf | Writes formatted data to a string
srand | Initializes a pseudo-random number generator
start_module | Starts execution of the designated module (do not wait until it initializes!)
stop_tone | Stops tone playing (turns the sound off)
str2cyid | Converts CyID from text form to cyid_t
str_1st_win | String "First player WINS!"
str_2nd_win | String "Second player WINS!"
str_again | String " again"
str_Declined_To_Play | String "%s declined to play with you"
str_Declined_To_Play_Game | String "%s declined to play %s"
str_Draw | String "Draw."
str_Draw_rejected | String "Draw rejected!"
str_Draw_suggestion | String "Your partner suggests a draw, do you agree?"
str_Draw_waiting | String "Waiting for answer..."
str_Enter_file_name | String "Enter file name"
STR_ICQ_MAX_LENGTH | Maximum length of the ICQ number
str_Illegal | String "Illegal"
str_Link_off | String "Link OFF."
str_Link_off_again | String "Link off.\nRestore connection?"
str_move | String " move"
str_no_CyPage | String "no CyPage"
str_Partner | String "Partner's"
str_Partner_surrender | String "Your partner surrendered.\nYou WIN!"
str_please | String " please..."
str_Really_exit | String "Do you really want to quit?"
str_Save_Changes | String "Do you wish to save changes?"
str_Score_Again | String "Your final score: %d.\nDo you want to start again?"
str_Tie_up | String "Tie."
str_wait | String " Wait,"
str_Waiting_link | String "Waiting for link..."
str_Waiting_SyPage | String "Waiting CyPage..."
str_You_lose | String "You lose."
str_You_win | String "You WIN!"
str_Your | String " Your"
strcat | Appends one string to another and terminates the resulting string with a null character
strchr | Finds a character in a string
strcmp | Compares characters from two strings
strcpy | Copies a string, including the terminating null character to the destination buffer
strends | Checks whether the string ends with a specified substring
strlen | Returns the length of a string, not including the terminating null character
strmatch | Checks wildcard match of the string to the pattern
strncmp | Compares characters from two strings
strncpy | Copies the initial count characters of the source string to the destination buffer
strrchr | Scans a string for the last occurrence of a character
strstarts | Checks whether a string starts with a specified substring
strstr | Finds a substring

T

TGraph | The implementation of raster and 2D-graphics. It is designated for work with primitive graphics such as rectangles, lines and pixels
Thread | The main thread object for the CyOS
Time | A time manipulation structure
TGraph_draw_hline | Draws a horizontal line from point ( x , y ) to point ( dx , y )
TGraph_draw_line | Draws a solid line from point ( x1 , y1 ) to point ( x2 , y2 )
TGraph_draw_rect | Draws a rectangular frame
TGraph_draw_rect_Ex | The extended version of the TGraph_draw_rect function
TGraph_draw_vline | Draws vertical line from point ( x , y ) to point ( x , dy )
TGraph_fill_rect | Fills a rectangle at the specified coordinates with the current color
TGraph_fill_rect_Ex | The extended version of the TGraph_fill_rect function
TGraph_fill_screen | Fills the screen with the color 'fc'
TGraph_get_buf_addr | Returns a pointer to an image of a TGraph object's destination
TGraph_get_bytes_total | Returns the screen buffer size, in bytes
TGraph_get_clip | Returns the clip region stored in the 'rc' object
TGraph_get_color | Returns a TGraph object's current color
TGraph_get_draw_mode | Returns the current draw mode of a TGraph object
TGraph_get_pixel | Returns the color of the pixel at coordinate ( x , y )
TGraph_put_background | Sets an image pointed by ptr_background as a background image
TGraph_scroll | Scrolls the rectangle defined by ( x, y, width, height ) parameters
TGraph_set_bkcolor | Sets the transparent color as the color defined in the 'color' parameter
TGraph_set_clip | Sets the clipping region
TGraph_set_clip_Ex | Sets the clipping region
TGraph_set_color | Sets the foreground color
TGraph_set_draw_mode | Sets the current draw mode of a TGraph object
TGraph_set_pixel | Sets the color for the pixel at the coordinates ( x, y )
time | Returns the current time in the system format (seconds since some date)
Time_clear_alarm_flag | Resets the alarm flag
Time_decode | Decodes 'time' and fill fields
Time_enable_alarm_int | Sets or resets the alarm flag
Time_encode | Packs fields into the time_t type
Time_get_RTC | Sets the fields according to the values read from the Real Time Clock (RTC)
Time_get_weekday | Calculates the weekday for the current date (Sunday is 0, Saturday is 6)
Time_set_RTC | Sets the Real Time Clock (RTC) according to its fields
timeout | Maximum timeout (in ms) between write() call and actual byte sending
tScrolls | Scroll mode
Type | Form type (rect or rounded box)
tBevelSidesTypes | The visible styles for creating a bevel's sides
tDialogStyle | Dialog styles
tEditCursorCommand | Commands for cursor positioning
tEditStyles | Edit box styles
text | Draws text in the specified color
textC | Draws text with specified colors for the text and the background
time_t | Represents time values in the time() function and Time object
tMResults | Predefined results that may be returned from modal forms
TRACE | Traces to the system console
trunc_spaces | Removes spaces from the string

U

update_people_around Selects the base channel, waits the timeout, and resets the work channel

V

va_arg | Retrieves the current argument from the list of optional arguments for variable argument function
va_end | Releases a list of optional arguments for variable argument function
va_list | Storage to hold information needed by the va_start(), va_arg() and va_end() macros
va_start | Initializes a list of optional arguments for variable argument function
vibrate | Turns the vibrator on (if index > 0) or off (if index is 0)
vsprintf | Writes formatted output using a pointer to a list of arguments

W

w | Rectangle's width
WaitResult | Com_wait_for_data() function results

X

x | Rectangle's x-coordinate
XOFF_char | Character used as XOFF
XON_char | Character used as XON
xtoi | Converts some ASCII number into long

Y

y | Rectangle's y-coordinate
year | Year - 1900, 99 means 1999

Z


Graphical Class Hierarchy

Class Hierarchy

System
Communications
Graphics
Interface Elements
Input and Output
Utilities


Processes and Modules

Defines
#define | PR_IDLE 5
#define | PR_NORMAL 50
#define | PR_RUNTIME 100

Typedefs
typedef int | priority_t

Enumerations
enum modulestate_t {
MODULE_OK = 0,
MODULE_BAD,
MODULE_TIMEOUT
}

Functions
long | init_module (struct module_t *ptr_module)
void | exit (int exit_code)
int | execute_module (char *sz_command_line, long *ptr_retcode, clock_t timeout)
bool | start_module (char *command_line)
void | increment_usage (void)
void | decrement_usage (void)
bool | has_focus (void)
bool | sleep (clock_t timeout)

Compounds
struct | Module | The CyOS Module
struct | module_t | The application module structure
struct | Process | A kind of thread that can process messages
struct | Queue | Messages queue; messages are stored in the queue
struct | SystemThread | Base object for all execution units (threads)
struct | Thread | The main thread object for the CyOS

Detailed Description

These structures and functions are used to control the application as a whole. You may want to look at cWinApp and module_t structures.

Define Documentation

#define PR_IDLE 5

Very low priority (for background tasks).

#define PR_NORMAL 50

Normal (medium) priority.

#define PR_RUNTIME 100

Very high priority (for runtime threads).

Typedef Documentation

typedef int priority_t

The thread priority.
Must be one of the following: PR_IDLE, PR_NORMAL or PR_RUNTIME.

See also:
PR_IDLE, PR_NORMAL, PR_RUNTIME.

Enumeration Type Documentation

enum modulestate_t

The result of the module's execution.

See also:
execute_module.
Enumeration values:
MODULE_OK | Module was successfully initialized.
MODULE_BAD | Module was bad.
MODULE_TIMEOUT | Intialization timeout.

Function Documentation

void decrement_usage ( void )

Decrements the reference count for the current module.

Returns:
None.
       #include <cybiko.h>
       ...
       increment_usage();
       ...
       //  During this time, the module cannot be unloaded.
       ...
       decrement_usage();
       ...
See also:
increment_usage.

int execute_module ( | char * sz_command_line,
 | long * ptr_retcode,
 | clock_t timeout )

Loads and executes the module, then waits for it's module_main to exits.
It blocks a timeout while module_main finishes, then stores it's returned value in the retcode parameter. Use it when you need to get returned code, and don't mind waiting till the module_main exits.

Parameters:
sz_command_line | A command string to start the module
ptr_retcode | The storage site for the module's returned code
timeout | Determines how long to wait for module_main to finish
Returns:
The result of the execution (one of the modulestate_t members)
       #include <cybiko.h>
       ...
       long retcode;
       ...
       // Executes an application.
       execute_module( "billiard.app", &retcode, 1000*60*10 );
       if( retcode ==  MODULE_TIMEOUT)
       {
         // The game time exceeded 10 minutes.
         ...
       }
       ...
See also:
start_module, modulestate_t

void exit ( int exit_code )

Exits current the thread with some code.

Parameters:
exit_code Exit code.
Returns:
None.
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       else
       {
         exit( 1 );
       }
       ...
       MSequence_dtor(  &intro_music );
       ...

bool has_focus ( void )

Tests whether the current process has the focus.

Returns:
TRUE if the current process has the focus, otherwise FALSE
       #include <cybiko.h>
       ...
       Process_request_focus( main_module.m_process );
       ...
       if( has_focus() )
       {
         //  Draws something.
         ...
       }
       ...

void increment_usage ( void )

Increments the reference count for the current module.

Returns:
None
       #include <cybiko.h>
       ...
       increment_usage();
       ...
       //  During this time, the module cannot be unloaded.
       ...
       decrement_usage();
       ...
See also:
decrement_usage.

long init_module ( struct module_t * ptr_module )

Module initializer.
You must call this function in each application to obtain a module.

Parameters:
module The pointer to a module_t object
Returns:
A pointer to the application's initialized module
       #include <cybiko.h>
       ...
       //  Application's main module
       struct module_t main_module;
       ...
       long main( int argc, char* argv[], bool start )
       {
         //  Initializes the application.
         init_module( &main_module );
         ...
      }

bool sleep ( clock_t timeout )

Pauses execution of the current thread.

Parameters:
The time span to sleep, measured in milliseconds
Returns:
FALSE if timeout has passed.
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone( 30 );
       sleep( 200 );
       play_tone( -1 );
       ...

bool start_module ( char * command_line )

Starts execution of the designated module (do not wait until it initializes!).

Returns:
TRUE if the module was launched, otherwise FALSE
       #include <cybiko.h>
       ...
       long retcode;
       ...
       // Executes an application.
       if( !start_module( "billiard.app" ) )
       {
         // Unable to launch the 'Billiard' application.
         ...
       }
       ...
See also:
execute_module.


Module Struct Reference

Collaboration diagram for Module:

Public Attributes
struct Archive* archive

Detailed Description

Modules are compound execution units. Thay consist of executable, relocatable sections that can be started in separate threads to create more threads and other CyOS objects. Modules know the archive files used to load them, and provide easy one-call access to the other resources stored inside them.

See also:
Processes and Modules

Member Data Documentation

struct Archive * archive

A pointer to the module's Archive object.


module_t Struct Reference

Collaboration diagram for module_t:

Public Attributes
struct DisplayGraphics* | m_gfx
struct cWinApp* | m_process

Detailed Description

Structure of the application module. Contains pointers to the graphics device context and to the current cywin application. Use this structure with the init_module() function.

See also:
init_module , Processes and Modules

Member Data Documentation

struct DisplayGraphics * m_gfx

Pointer to graphics device context.

Parameters:
module The pointer to a module_t object

struct cWinApp * m_process

Pointer to the current cywin application.


Process Struct Reference

Inheritance diagram for Process

Collaboration diagram for Process:

Public Methods
bool | Process_pause (struct Process *ptr_process, clock_t timeout)
struct Process* | Process_request_focus (struct Process *ptr_process)
bool | Process_has_focus (struct Process *ptr_process)
struct DisplayGraphics* | Process_get_display (void)
char* | Process_get_name (struct Process *ptr_process)
void | Process_put_message (struct Process *ptr_process, struct Message *ptr_message)
struct Message* | Process_get_message (struct Process *ptr_process, long timeout, int min, int max)
struct Message* | Process_peek_message (struct Process *ptr_process, bool remove, int min, int max)

Detailed Description

A thread enabled to process messages. The System has the Thread function to do tasks, and the Process function to process messages such as input events from the keyboard, system messages, and radio-sent communication messages. The Process function can have input focus; you can and ask for it by calling Process_request_focus(). When the Process has the focus, it gets all input events from the keyboard.

See also:
Processes and Modules

Member Function Documentation

struct DisplayGraphics * Process_get_display ( void )

Retrieves a DisplayGraphics object to the access display.

Returns:
A pointer to the DisplayGraphics object
       #include <cybiko.h>
       ...
       struct Bitmap bmp;
       ...
       //  Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       ...
       //  Draws bitmap.
       Graphics_draw_bitmap( Process_get_display(), &bmp, 30, 40, BM_NORMAL );
       ...
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
       ...

struct Message * Process_get_message ( | struct Process * ptr_process,
 | long timeout,
 | int min,
 | int max )

Returns the message after the specified interval.
The calling thread waits until the first message appears in the queue. Be careful not to overload the queue overflow. Delete message when you finished with it.

Parameters:
ptr_process | A pointer to the initialized Process object.
timeout | Timeout value(in milliseconds)
min | deprecated
max | deprecated
Returns:
Pointer to the Message if one is in the Process' queue, or 0 if a timeout occurs
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = Process_get_message( main_module.m_process, 0, 1, MSG_USER );
       if( ptr_message->msgid == MSG_KEYDOWN )
       {
         if( Message_get_key_param( ptr_message )->scancode == MSG_ESC )
         {
           //  Processes key 'Esc'.
         }
       }
       ...
       Message_delete( ptr_message );
       ...
See also:
Process_peek_message.

char * Process_get_name ( struct Process * ptr_process )

Retrieves the Process' name.

Parameters:
ptr_process A pointer to the initialized Process object
Returns:
The Process' name
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       TRACE("Hello from the %s process",
             Process_get_name( main_module.m_process ) );
       ...

bool Process_has_focus ( struct Process * ptr_process )

Tests whether the Process has the focus.

Parameters:
ptr_process A pointer to the initialized Process object
Returns:
TRUE if the Process has the focus, otherwise FALSE
       #include <cybiko.h>
       ...
       Process_request_focus( main_module.m_process );
       ...
       if( Process_has_focus( main_module.m_process ) )
       {
         //  Draws something.
         ...
       }
       ...

bool Process_pause ( | struct Process * ptr_process,
 | clock_t timeout )

Pauses execution of the Process.

Parameters:
ptr_process | A pointer to the Process initialized object
timeout | The time span to sleep, in milliseconds
Returns:
FALSE if the timeout is passed
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone(30);
       Process_pause(main_module.m_process, 200);
       play_tone(-1);
       ...

struct Message * Process_peek_message ( | struct Process * ptr_process,
 | bool remove,
 | int min,
 | int max )

Peeks or gets message from the queue.
If remove is TRUE, the message will be removed. This function does not wait for a message to be available; it returns 0 immediately if there are no messages in the specified range. Don't use this function unless you really need to.

Parameters:
ptr_process | A pointer to the initialized Process object
remove | If TRUE the message will be removed from the message queue
min | Specifies the lowest message value to be retrieved, as an integer value
max | Specifies the highest message value to be retrieved, as an integer value
Returns:
A pointer to the Message if one is in the Process' queue, otherwise 0
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       //  Removes all keyboard messages from the queue.
       while(ptr_message = Process_peek_message( main_module.m_process, TRUE, MSG_KEYDOWN, MSG_KEYDOWN ))
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Process_get_message.

void Process_put_message ( | struct Process * ptr_process,
 | struct Message * ptr_message )

Puts a Message in the Process' Queue.

Parameters:
ptr_process | A pointer to the initialized Process object
ptr_message | A pointer to the message to send
Returns:
None
       #include <cybiko.h>
       ...
       #define MSG_MAKE_TASK  MSG_USER + 1
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = Process_get_message( main_module.m_process, 0, 1, MSG_MAKE_TASK );
       if( ptr_message->msgid == MSG_MAKE_TASK )
       {
         ...
         //  Performs some periodical calculation.
         ...
         Process_pause( main_module.m_process, 250 );
         Process_put_message( main_module.m_process, ptr_message );
       }
       else
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Process_get_message , Process_peek_message.

struct Process * Process_request_focus ( struct Process * ptr_process )

Asks the system to activate the Process (pass the focus).
Once it has the focus, the Process has actual access to the screen and receives the keyboard and pointing device events. When the system gets this call, it passes the focus to the Process that asked for it by sending it the message MSG_GOTFOCUS. Then the system sends the message MSG_LOSTFOCUS to the Process that had the focus previously.

Parameters:
ptr_process A pointer to the initialized Process object
Returns:
Process that had the focus before this call
       #include <cybiko.h>
       ...
       Process_request_focus( main_module.m_process );
       ...
       if( Process_has_focus( main_module.m_process ) )
       {
         //  Draws something.
         ...
       }
       ...


Queue Struct Reference

Public Methods
struct Message* | Queue_peek_message (struct Queue *ptr_queue, bool remove, int min, int max)
struct Message* | Queue_get_message (struct Queue *ptr_queue, long timeout, int min, int max)
void | Queue_put_message (struct Queue *ptr_queue, struct Message *ptr_message)

Detailed Description

Queues can peek at and/or remove messages from a specified range. They have names and are targets for messages; in particular, all processes have queues and thus can get messages.

See also:
Processes and Modules

Member Function Documentation

struct Message * Queue_get_message ( | struct Queue * ptr_queue,
 | long timeout,
 | int min,
 | int max )

Returns the message from the specified interval.
The calling thread waits until the first message appears in the queue. Be careful not to overload, the queue. Delete the message when you are finished with it.

Parameters:
ptr_queue | A pointer to the initialized Queue object
timeout | Timeout value(in milliseconds)
min | deprecated
max | deprecated
Returns:
A pointer to the Message if one is in the queue, or 0 if a timeout occurs
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = Queue_get_message( main_module.m_process,
                                        0,
                                        1,
                                        MSG_USER );
       if( ptr_message->msgid == MSG_KEYDOWN )
       {
         if( Message_get_key_param( ptr_message )->scancode == MSG_ESC )
         {
           //  Processes key 'Esc'.
         }
       }
       ...
       Message_delete( ptr_message );
       ...
See also:
Queue_peek_message.

struct Message * Queue_peek_message ( | struct Queue * ptr_queue,
 | bool remove,
 | int min,
 | int max )

Peeks at or gets a message from the queue.
If remove is TRUE, the message will be removed. It does not wait for a message to be available; it returns 0 immediately if there are no messages in the specified range. Don't use this function unless really need to.

Parameters:
ptr_queue | A pointer to the initialized Queue object
remove | If TRUE, the message will be removed from the message queue
min | Specifies the lowest message value to be retrieved, as an integer
max | Specifies the highest message value to be retrieved, as an integer
Returns:
A pointer to the Message if one is in the queue, otherwise 0
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       //  Removes all keyboard messages from the queue.
       while( ptr_message = Queue_peek_message( main_module.m_process,
                                                TRUE,
                                                MSG_KEYDOWN,
                                                MSG_KEYDOWN ) )
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Queue_get_message.

void Queue_put_message ( | struct Queue * ptr_queue,
 | struct Message * ptr_message )

Puts a Message in the Queue.

Parameters:
ptr_queue | A pointer to the initialized Queue object
ptr_message | A pointer to the specified message to put
Returns:
None
       #include <cybiko.h>
       #define MSG_MAKE_TASK  MSG_USER + 1
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = Queue_get_message( main_module.m_process,
                                        0,
                                        1,
                                        MSG_MAKE_TASK );
       if( ptr_message->msgid == MSG_MAKE_TASK )
       {
         ...
         //  Performs some periodical calculation.
         ...
         sleep( 250 );
         Queue_put_message( main_module.m_process, ptr_message );
       }
       else
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Queue_get_message , Queue_peek_message.


SystemThread Struct Reference

Inheritance diagram for SystemThread

Collaboration diagram for SystemThread:

Public Methods
bool | SystemThread_pause (struct SystemThread *ptr_thread, clock_t timeout)
priority_t | SystemThread_get_priority (struct SystemThread *ptr_system_thread)
void | SystemThread_set_priority (struct SystemThread *ptr_system_thread, priority_t priority)

Public Attributes
struct Module* | module

Detailed Description

Base object for all execution units (threads). This object defines the basic object that makes an execution thread.

See also:
Processes and Modules

Member Function Documentation

priority_t SystemThread_get_priority ( struct SystemThread * ptr_system_thread )

Returns a thread's priority.

Parameters:
ptr_system_thread A pointer to the SystemThread initialized object
Returns:
Priority of the thread
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       if( SystemThread_get_priority( main_module.m_process ) <  PR_NORMAL )
           SystemThread_set_priority( main_module.m_process, PR_NORMAL );
       ...
See also:
SystemThread_set_priority, PR_IDLE, PR_NORMAL, PR_RUNTIME.

bool SystemThread_pause ( | struct SystemThread * ptr_thread,
 | clock_t timeout )

Pauses execution of the thread.

Parameters:
ptr_thread | A pointer to the SystemThread initialized object
timeout | The time span to sleep, in milliseconds
Returns:
FALSE if the timeout has passed
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone( 30 );
       SystemThread_pause( main_module.m_process, 200 );
       play_tone( -1 );
       ...

void SystemThread_set_priority ( | struct SystemThread * ptr_system_thread,
 | priority_t priority )

Changes the thread's priority.

Parameters:
ptr_system_thread | A pointer to the SystemThread initialized structure
priority | The thread priority, on a scale from PR_IDLE to PR_RUNTIME
Returns:
None
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       if( SystemThread_get_priority( main_module.m_process ) <  PR_NORMAL )
           SystemThread_set_priority( main_module.m_process, PR_NORMAL );
       ...
See also:
SystemThread_get_priority, PR_IDLE, PR_NORMAL, PR_RUNTIME.

Member Data Documentation

struct Module * module

Pointer to the module to which the thread belongs.


Thread Struct Reference

Inheritance diagram for Thread

Collaboration diagram for Thread:

Detailed Description

The CyOS threading model is based on the Threads' status. Threads are executed concurrently by priority: the higher the priority (bigger numerical value), the more time the Thread can have. No low-priority thread will be executed until there is at least one other thread with a higher priority; Threads of the same priority share more or less the same time slices for the CPU. A Thread's natural state of being is to wait. Threads spend most of the time waiting, for a timeout, a message, a file operation, a Flag or Mutex state, or many other reasons. If the OS dispatcher detects a Thread with a higher priority than PR_IDLE that does not spend much time waiting, the OS decides that it is a zombie thread (a dead thread that just eats system resources) and kills it.

See also:
Processes and Modules


Synchronization

Functions
void set_hourglass (bool enable)

Compounds
struct | Flag | The flag synchronization object (aka Semaphore)
struct | Flagex | Synchronization object that combines FLAG and MutEX (FLAGEX)
struct | Mutex | Mutex a kind of a synchronization object that provides MUTually EXclusive (MUTEX) access to some part of the code (in some systems this is also known as Resource)

Detailed Description

Synchronization objects are used to synchronize access to shared objects. In many, cases you can use the Mutex structure.

Function Documentation

void set_hourglass ( bool enable )

When you start this function, the system starts a special Thread to show the picture, which can eat up to 10-11% of processor time; after you stop it, don't forget to remove it from the screen by repainting it.

Parameters:
enable TRUE to start the show, FALSE to stop it
Returns:
None
       #include <cywin.h>
       ...
       long obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       long current_value;
       long size;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       size = Output_get_size( ptr_output )/sizeof(long);
       set_hourglass( TRUE );
       for( index = 0; index < size; index++ )
       {
         current_value = obtain_new_value();
         Output_write_dword( ptr_output, current_value );
       }
       set_hourglass( FALSE );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...


Flag Struct Reference

Public Methods
struct Flag* | Flag_ctor (struct Flag *ptr_flag, char *name, bool set)
void | Flag_set (struct Flag *ptr_flag)
void | Flag_set_Ex (struct Flag *ptr_flag, bool state)
void | Flag_clear (struct Flag *ptr_flag)
bool | Flag_is_set (struct Flag *ptr_flag)
void | Flag_flip (struct Flag *ptr_flag)
bool | Flag_wait_set (struct Flag *ptr_flag, clock_t timeout)
bool | Flag_wait_clear (struct Flag *ptr_flag, clock_t timeout)
bool | Flag_wait (struct Flag *ptr_flag, bool set, clock_t timeout)
void | Flag_dtor (struct Flag *ptr_flag, int memory_flag)

Detailed Description

This synchronization object has two states: set and clear. Threads may wait for the flag be in the specific state and change it.

See also:
Synchronization

Member Function Documentation

void Flag_clear ( struct Flag * ptr_flag )

Sets a flag in a clear state, or changes the flag's state to clear.
If there are threads waiting for the flag object's state to become clear, all of them will become active. If there were higher priority threads already waiting before this one, the context switch may happen immediately.

Parameters:
ptr_flag A pointer to the initialized Flag object
Returns:
None
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

struct Flag * Flag_ctor ( | struct Flag * ptr_flag,
 | char * name,
 | bool set )

Creates a named flag.

Parameters:
ptr_flag | A pointer to the Flag structure
name | The name of the flag
set | if TRUE, then flag state will be set; otherwise it will clear
Returns:
A pointer to the initialized Flag object
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

void Flag_dtor ( | struct Flag * ptr_flag,
 | int memory_flag )

Destructor.

Parameters:
ptr_flag | A pointer to the initialized Flag object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

void Flag_flip ( struct Flag * ptr_flag )

Flips a flag's state from set to clear or vice-versa.

Parameters:
ptr_flag A pointer to the initialized Flag object
Returns:
None
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

bool Flag_is_set ( struct Flag * ptr_flag )

Returns TRUE if a flag is in the set state.

Parameters:
ptr_flag A pointer to the initialized Flag object
Returns:
TRUE if a flag is in the set state
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       while( Flag_is_set( &data_busy ) )
       {
         cWinApp( main_module.m_process, 250 );
       }
       Flag_set( &data_busy );
       ...
       // Uses shared data.
       ...
       Flag_clear( &data_busy );
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

void Flag_set ( struct Flag * ptr_flag )

Sets a flag, or changes the flag to the set state.
If there are threads waiting for the flag object's state to become set, all of them will become active. If there were higher priority threads already waiting before this one, the context switch may happen immediately. Does nothing if the flag is already set.

Parameters:
ptr_flag A pointer to the Flag structure
Returns:
None
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_clear( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...
See also:
Flag_set_Ex.

void Flag_set_Ex ( | struct Flag * ptr_flag,
 | bool state )

Sets the flag to a specified state, or changes the flag's state to set or clear.
If there are threads waiting for the flag object's state to change this way, all of them will become active. If there were higher priority threads already waiting before this one, the context switch may happen immediately.

Parameters:
ptr_flag | A pointer to the initialized Flag object
state | The desired state; "TRUE" for set, "FALSE" for clear
Returns:
None
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set_Ex( &data_busy, TRUE );
         ...
         // Uses shared data.
         ...
         Flag_set_Ex( &data_busy, FALSE );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...
See also:
Flag_set.

bool Flag_wait ( | struct Flag * ptr_flag,
 | bool set,
 | clock_t timeout )

Waits for a specified state.
If the flag is already in the desired state, it returns; otherwise it waits for a specified timeout.

Parameters:
ptr_flag | A pointer to the initialized Flag object
set | 'true' if you need to wait for the set state, 'false' for the clear state
timeout | Time to wait, in milliseconds. (0 means forever)
Returns:
TRUE on success, FALSE on timeout
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait( &data_busy, FALSE, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

bool Flag_wait_clear ( | struct Flag * ptr_flag,
 | clock_t timeout )

Waits for the flag's state to become clear.
If the flag is already clear, it returns immediately. If the flag is set, it waits until the timeout expires or the flag state changes.

Parameters:
ptr_flag | A pointer to the initialized Flag object
timeout | Time to wait, in milliseconds. (0 means forever)
Returns:
TRUE on success, FALSE on timeout
       #include <cywin.h>
       ...
       struct Flag data_busy;
       ...
       Flag_ctor( &data_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_clear( &data_busy, 1000 ) )
       {
         Flag_set( &data_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_busy, LEAVE_MEMORY );
       ...

bool Flag_wait_set ( | struct Flag * ptr_flag,
 | clock_t timeout )

Wait the flag's state to change to set.
If flag is already set, it returns immediately. If the flag is clear, it waits until the timeout expires or flag's state changes.

Parameters:
ptr_flag | A pointer to the initialized Flag object
timeout | Time to wait, in milliseconds (0 means forever)
Returns:
TRUE on success, FALSE on timeout
       #include <cywin.h>
       ...
       struct Flag data_not_busy;
       ...
       Flag_ctor( &data_not_busy, "shared_data", FALSE );
       ...
       if( Flag_wait_set( &data_not_busy, 1000 ) )
       {
         Flag_clear( &data_not_busy );
         ...
         // Uses shared data.
         ...
         Flag_flip( &data_not_busy );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Flag_dtor( &data_not_busy, LEAVE_MEMORY );
       ...


Flagex Struct Reference

Inheritance diagram for Flagex

Collaboration diagram for Flagex:

Public Methods
struct Flagex* | Flagex_ctor (struct Flagex *ptr_flagex, char *name)
bool | Flagex_wait (struct Flagex *ptr_flagex, clock_t timeout)
void | Flagex_notify (struct Flagex *ptr_flagex)
bool | Flagex_is_locked (struct Flagex *ptr_flagex)
bool | Flagex_lock (struct Flagex *ptr_flagex, clock_t timeout)
void | Flagex_unlock (struct Flagex *ptr_flagex)
void | Flagex_dtor (struct Flagex *ptr_flagex, int memory_flag)

Detailed Description

A Flag with Exclusion. Flagex is a son of Mutex that contains a Flag. Hence the name, a combination of FLAG and mutEX. It is a sort of synchronization object you can use when your object needs both to implement a wait-for-notification function as well as to lock and unlock like Mutex objects can. It works on the same principle as Java's "monitor lock." The main difference is that Flagex cannot notify a single thread; Flagex_notify is the equivalent of Java's Object.notifyAll().

Flagex offers three main functions:

  • Locks and unlocks objects with Flagex_lock and Flagex_unlock, the same way you lock and unlock Mutex objects.
  • Waits for notification with Flagex_wait.
  • Notifies waiting threads (waking them) with Flagex_notify.
The key is that Flagex_wait and Flagex_notify only function when the object is Flagex_locked. When your object wakes after Flagex_wait, the system regains the lock on the Flagex for your thread. After you call Flagex_wait, the thread is released so another thread can Flagex_lock it and then Flagex_notify it.

Use this method when you need to synchronize exclusive access to a specific object until another process concludes on the same object. This allows the accessing thread both to wait and to synchronize its action with the other thread.
See also:
Synchronization

Member Function Documentation

struct Flagex * Flagex_ctor ( | struct Flagex * ptr_flagex,
 | char * name )

Constructs a named Flagex object.

Parameters:
ptr_flagex | A pointer to the Flagex structure
name | The name of the Flagex object
Returns:
A pointer to the initialized Flagex object
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       if( Flagex_wait( &wait_for_data, 1000 ) )
       {
         // Uses shared data.
         ...
       }
       else
       {
         TRACE( "Timeout while waiting for data." );
       }
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

void Flagex_dtor ( | struct Flagex * ptr_flagex,
 | int memory_flag )

Destructor.

Parameters:
ptr_flagex | A pointer to the initialized Flagex object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       if( Flagex_wait( &wait_for_data, 1000 ) )
       {
         // Uses shared data.
         ...
       }
       else
       {
         TRACE( "Timeout while waiting for data." );
       }
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

bool Flagex_is_locked ( struct Flagex * ptr_flagex )

Checks whether Mutex is locked.

Parameters:
ptr_flagex A pointer to the initialized Flagex object
Returns:
TRUE if Mutex is locked
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       while( Flagex_is_locked( &wait_for_data ) )
       {
          cWinApp( main_module.m_process, 250 );
       }
       Flagex_lock( &wait_for_data, 0 );
       ...
       // Uses shared data.
       ...
       Flagex_unlock( &wait_for_data);
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

bool Flagex_lock ( | struct Flagex * ptr_flagex,
 | clock_t timeout )

Returns a lock.
It attempts to get the lock for specified time. Note that if you already locked it, another Flagex_lock() operation has no additive effect. The first Flagex_unlock() call unlocks it immediately no matter how many times you've called the Flagex_lock() method. Be careful when designing your Flagexes logic!

Parameters:
ptr_flagex | A pointer to the initialized Flagex object
timeout | Determines how long to wait if a lock can not be acquired; (0 means forever)
Returns:
TRUE if a lock was acquired, FALSE if timeout expired
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       while( Flagex_is_locked( &wait_for_data ) )
       {
          cWinApp( main_module.m_process, 250 );
       }
       Flagex_lock( &wait_for_data, 0 );
       ...
       // Uses shared data.
       ...
       Flagex_unlock( &wait_for_data);
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...
See also:
Flagex_unlock.

void Flagex_notify ( struct Flagex * ptr_flagex )

Notifies all waiting threads.
All threads that called Flagex_wait() for this object will be waked up. Note that they won't start until you will unlock the object, and that most priority one (and, though not guaranteed, first called wait() from top priority threads) will get the lock and actually start. You must have a lock on the object to call this method.

Parameters:
ptr_flagex A pointer to the initialized Flagex object
Returns:
None
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       // Prepares data.
       ...
       Flagex_notify( &notify ;
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...

void Flagex_unlock ( struct Flagex * ptr_flagex )

Unlocks Flagex.
Note that if you did not lock it before, the system ignores the unlock command and prints warning on the console. Also be warned: Flagex_unlock() releases the lock immediately, no matter how many times Flagex_lock() was called. Only the first Flagex_unlock() works; any repeared calls will be ignored.

Parameters:
ptr_flagex A pointer to the initialized Flagex object
Returns:
None
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       while( Flagex_is_locked( &wait_for_data ) )
       {
          cWinApp( main_module.m_process, 250 );
       }
       Flagex_lock( &wait_for_data, 0 );
       ...
       // Uses shared data.
       ...
       Flagex_unlock( &wait_for_data);
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...
See also:
Flagex_lock.

bool Flagex_wait ( | struct Flagex * ptr_flagex,
 | clock_t timeout )

Waits for notification.
Puts the calling thread to sleep until some other thread calls Flagex_notify(). You must have a lock on this object to call it.

Parameters:
ptr_flagex | A pointer to the initialized Flagex object
timeout | Determines how long to wait, in milliseconds ( 0 means forever)
Returns:
TRUE on notification and FALSE on timeout
       #include <cywin.h>
       ...
       struct Flagex wait_for_data;
       ...
       Flagex_ctor( &wait_for_data, "data_ready" );
       ...
       if( Flagex_wait( &wait_for_data, 1000 ) )
       {
         // Uses shared data.
         ...
       }
       else
       {
         TRACE( "Timeout while waiting for data." );
       }
       ...
       Flagex_dtor( &wait_for_data, LEAVE_MEMORY );
       ...


Mutex Struct Reference

Inheritance diagram for Mutex

Public Methods
struct Mutex* | Mutex_ctor (struct Mutex *ptr_mutex, char *name)
bool | Mutex_is_locked (struct Mutex *ptr_mutex)
bool | Mutex_lock (struct Mutex *ptr_mutex, clock_t timeout)
void | Mutex_unlock (struct Mutex *ptr_mutex)
void | Mutex_dtor (struct Mutex *ptr_mutex, int memory_flag)

Detailed Description

Mutex is a kind of a synchronization object that provides MUTually EXclusive (MUTEX) access to some part of the code (in some systems this is also known as Resource). Mutex can be locked by a Thread using the Mutex_lock method, then released. Only one thread at a time owns the lock on any given Mutex when the lock is released, the next thread (if any) waiting for the Mutex is activated.

If a thread tries to lock a Mutex that is already locked, the thread will be set to wait until a timeout expires or until the Mutex object is unlocked. Take care to prevent deadlocks: for example, when one thread owns Mutex m1 and tries to lock Mutex m2,while a second thread already owns Mutex m2 and is trying to lock Mutex m1. Deadlocks can occur not only with Mutexes, but practically with any set of synchronization objects. Since the OS can not yet detect all deadlocks, it is up to programmers to design their systems accordingly.

It doesn't matter how long you've locked a Mutex object-it unlocks the first time you call Mutex_unlock(). The system does not allow unowned Mutex objects to be unlocked.

See also:
Synchronization

Member Function Documentation

struct Mutex * Mutex_ctor ( | struct Mutex * ptr_mutex,
 | char * name )

Constructs the named Mutex object.

Parameters:
ptr_mutex | A pointer to the Mutex structure
name | The name of the Mutex object
Returns:
A pointer to the initialized Mutex object
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...

void Mutex_dtor ( | struct Mutex * ptr_mutex,
 | int memory_flag )

Destructor.

Parameters:
ptr_mutex | A pointer to the initialized Mutex object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...

bool Mutex_is_locked ( struct Mutex * ptr_mutex )

Checks whether the Mutex is locked.

Parameters:
ptr_mutex A pointer to the Mutex structure
Returns:
TRUE if the Mutex object is locked
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       while( Mutex_is_locked( &data_mutex ) )
       {
         cWinApp( main_module.m_process, 250 );
       }
       Mutex_lock( &data_mutex, 0 );
       ...
       // Uses shared data.
       Mutex_unlock( &data_mutex );
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...

bool Mutex_lock ( | struct Mutex * ptr_mutex,
 | clock_t timeout )

Returns a lock.
Attempts to get the lock for specified time. Note that if you already locked an object, another Mutex_lock() operations does absolutely nothing, and the first Mutex_unlock() call unlocks it immediately no matter how many times you've called the Mutex_lock() method. Be careful when designing your Mutex logic!

Parameters:
ptr_mutex | A pointer to the initialized Mutex object
timeout | Determines how long wait if a lock can not be acquired (0 means forever)
Returns:
TRUE if a lock was acquired, FLASE if timeout has expired
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...
See also:
Mutex_unlock.

void Mutex_unlock ( struct Mutex * ptr_mutex )

Unlocks a Mutex object.
Note that if you did not Mutex_lock() it before, the system ignores the unlock command and prints a warning on the console. Also be warned: Mutex_unlock() releases the lock immediately. No matter how many times Mutex_lock() was called, only the first Mutex_unlock() works. any repeared commands will be ignored.

Parameters:
ptr_mutex A pointer to the initialized Mutex object
Returns:
None
       #include <cywin.h>
       ...
       struct Mutex data_mutex;
       ...
       Mutex_ctor( &data_mutex, "shared_data" );
       ...
       if( Mutex_lock( &data_mutex, 1000 ) )
       {
         // Uses shared data.
         ...
         Mutex_unlock( &data_mutex );
       }
       else
       {
         TRACE( "Timeout while trying to access." );
       }
       ...
       Mutex_dtor( &data_mutex, LEAVE_MEMORY );
       ...
See also:
Mutex_lock.


Memory Management

Defines
#define | FREE_MEMORY 3
#define | LEAVE_MEMORY 2

Functions
char* | malloc (size_t size)
void* | calloc (size_t number, size_t size)
void* | realloc (void *ptr_memory_block, size_t new_size)
void | free (void *ptr_memory_block)
bool | is_low_memory (void)
size_t | get_safety_pool_size (void)
void* | memset (void *ptr_buffer, int value, size_t size)
void* | memcpy (void *ptr_buffer, void *ptr_source, size_t size)
void* | memmove (void *dst, void *src, size_t size)
int | memcmp (void *ptr_buff_1, void *ptr_buff_2, size_t size)
void | memory_dump (void *ptr_memory, int size, int string_length)

Detailed Description

CyOS routines you can use to allocate, manipulate and free memory.

Define Documentation

#define FREE_MEMORY 3

Frees the memory block allocated for the object (used in destructor).

#define LEAVE_MEMORY 2

Doesn't free the memory block allocated for the object (used in destructor).

Function Documentation

void * calloc ( | size_t number,
 | size_t size )

Allocates an array in memory, with elements initialized to 0.
You can only free this memory block - by calling free().

Parameters:
number | the number of elements to allocate
size | the length in bytes of each element.
Returns:
a void pointer to the allocated space, or NULL if there is insufficient memory available
       #include <cybiko.h>
       #define  MAX_OBJECTS     100
       ...
       struct cObject* ptr_object_array;
       ...
       ptr_object_array = (struct cObject*)calloc( MAX_OBJECTS,
                                                   sizeof(struct cObject) );
       ...
       free(ptr_object_array);
       ...
See also:
free.

void free ( void * ptr_memory_block )

Frees a memory block.

Parameters:
ptr_memory_block a pointer to previously allocated memory block
Returns:
None
       #include <cybiko.h>
       #define  MAX_STR_LEN     256
       ...
       char* sz_string;
       ...
       sz_string = (char*)malloc( MAX_STR_LEN );
       ...
       free(sz_string);
       ...
See also:
malloc, calloc, realloc.

size_t get_safety_pool_size ( void )

Returns safety pool size.

Returns:
maximum size of the memory pool that can be allocated.
       #include <cybiko.h>
       ...
       if ( get_safety_pool_size() < 1024 )
       {
         TRACE( "Error! Not enough memory." );
         return -1;
       }
       ...

bool is_low_memory ( void )

Returns low memory alarm.
The system sets it automatically when the dynamic memory pool drops dangerously low. All applications should check dynamic memory. When TRUE is returned, the application should free up all possible dynamically allocated memory. When it is set to TRUE.

Returns:
TRUE if memory is low
       #include <cybiko.h>
       ...
       if( is_low_memory() )
       {
         TRACE( "Warning! Low memory." );
       }
       ...

char * malloc ( size_t size )

Allocates memory blocks.
Afterward you must free this memory block by calling free().

Parameters:
size number of bytes to allocate
Returns:
a void pointer to the allocated space, or NULL if there is insufficient memory available
       #include <cybiko.h>
       #define  MAX_STR_LEN     256
       ...
       char* sz_string;
       ...
       sz_string = (char*)malloc( MAX_STR_LEN );
       ...
       free(sz_string);
       ...
See also:
free.

int memcmp ( | void * ptr_buff_1,
 | void * ptr_buff_2,
 | size_t size )

Compares characters in two buffers.

Parameters:
ptr_buff_1 | a pointer to first buffer.
ptr_buff_2 | a pointer to second buffer.
size | number of characters to compare.
Returns:
0 if ptr_buff_1 identical to ptr_buff_2. Positive value if ptr_buff_1 greater(in lexical meaning) than ptr_buff_2. Negative value if ptr_buff_1 greater(in lexical meaning) than ptr_buff_2.
       char* string_1 = "AAAAAAAAAB";
       char* string_2 = "AAAAAAAAAA";
       ...
       if( !memcmp( string_1, string_2, 10 ) )
       {
         //  Buffers are not identical, because
         //  string_1 is greater then string_2 in lexical meaning.
         ...
       }
       ...

void * memcpy ( | void * ptr_buffer,
 | void * ptr_source,
 | size_t size )

Copies characters between buffers.
If the source and destination overlap, this function does not ensure that the original source bytes in the overlapping region are copied before being overwritten. Use memmove() to handle overlapping regions.

Parameters:
ptr_buffer | a pointer to destination.
ptr_source | a pointer to source.
size | number of characters to copy.
Returns:
a pointer to destination.
       #include <cybiko.h>
       ...
       const char* sz_base_string = "Hello,";
       const char* sz_name = "word";
       char* sz_string[20];
       ...
       memcpy( sz_string,
               sz_base_string,
               strlen( sz_base_string ) );
       memcpy( sz_string + strlen( sz_string ),
               sz_name,
               strlen( sz_name ) );
       memcpy( sz_string + strlen( sz_string ),
               "!",
               2 );
       //  Traces Hello, world!
       TRACE( "Result: %s", sz_string );
       ...
See also:
memmove.

void * memmove ( | void * dst,
 | void * src,
 | size_t size )

Moves one buffer to another.
If some regions of the source area and the destination overlap, memmove() ensures that the original source bytes in the overlapping region are copied before being overwritten.

Parameters:
ptr_buffer | a pointer to destination.
ptr_source | a pointer to source.
size | number of characters to copy.
Returns:
a pointer to destination.
       #include <cybiko.h>
       ...
       const char* sz_string = "The funny black cat.";
       ...
       memmove( sz_string + 4, sz_string + 10, 6 );
       //  Traces "The black black cat."
       TRACE( "Result: %s", string );
See also:
memcpy.

void memory_dump ( | void * ptr_memory,
 | int size,
 | int string_length )

Trace memory dump.

Parameters:
ptr_memory | pointer to the memory dump
size | the size of the memory dump
string_length | the maximum length of a string on the console
Returns:
None
        #include <cywin.h>
        ...
        char raw_data[ 256 ];
        ...
        //  Fills raw_data array.
        ...
        memory_dump( raw_data, 256, 16 );
        ...

void * memset ( | void * ptr_buffer,
 | int value,
 | size_t size )

Sets buffers to a specified character.

Parameters:
ptr_buffer | a pointer to destination.
value | a character to set.
size | number of characters.
Returns:
a pointer to destination.
       #include <cybiko.h>
       #define MAX_PLAYER      10
       ...
       struct Point
       {
         int x;
         int y;
       } players_coordinates[MAX_PLAYER];
       ...
       //  Initializes players' coordinates.
       memset( players_coordinates, 0, MAX_PLAYER*sizeof(struct Point) );
       ...

void * realloc ( | void * ptr_memory_block,
 | size_t new_size )

Reallocates memory blocks.
Afterward you must free this memory block by calling free().

Parameters:
ptr_memory_block | pointer to a previously allocated memory block
new_size | new size in bytes
Returns:
a pointer to the reallocated memory block
       #include <cybiko.h>
       ...
       char* sz_string;
       char* sz_source_string;
       ...
       sz_string = (char*)malloc( 10 );
       ...
       if( strlen( sz_source_string ) <= 10)
       {
         sz_string = (char*)realloc( sz_string,
                                     strlen( sz_source_string ) + 1 );
       }
       ...
       free(sz_string);
       ...
See also:
free.


Time-related

Typedefs
typedef long | clock_t
typedef clock_t | time_t

Functions
clock_t | clock (void)
time_t | time (void)
time_t | get_trusted_time (void)

Compounds
struct Time A time manipulation structure

Detailed Description

Some functions for setting and changing the date and time. Please look at the Time structure

Typedef Documentation

typedef long clock_t

Stores time values: used by the clock() function.

See also:
clock.

typedef clock_t time_t

Represents time values in the time() function and Time object.

See also:
time.

Function Documentation

clock_t clock ( void )

Returns the time from the system startup in milliseconds; updated every 10 mS.

Returns:
a clock_t value.
       #include <cybiko.h>
       ...
       int value;
       ...
       // Initializes a pseudorandom sequence.
       srand( clock() );
       ...
       value = random( 10 );

time_t get_trusted_time ( void )

Returns trusted time.
This time is synchronized with the Cybiko web server. The user cannot change the trusted time.

Returns:
The trusted time.
       #include <cybiko.h>
       ...
       struct Time time;
       ...
       Time_decode( &time, get_trusted_time() );
       //  Synchronizes real time clock with the trusted time.
       Time_set_RTC( &time );
       ...

time_t time ( void )

Returns the current time in the system format (seconds since some date).

Returns:
Time in the time_t format (seconds since some date).
       #include <cybiko.h>
       ...
       int week_day;
       struct Time time;
       ...
       Time_decode( &time, time() );
       ...
       week_day = Time_get_weekday( &time );
See also:
Time_encode.


Time Struct Reference

Public Methods
void | Time_decode (struct Time *ptr_time, time_t time)
time_t | Time_encode (struct Time *ptr_time)
bool | Time_set_RTC (struct Time *ptr_time)
bool | Time_get_RTC (struct Time *ptr_time)
int | Time_get_weekday (struct Time *ptr_time)
int | Time_clear_alarm_flag (void)
bool | Time_enable_alarm_int (bool enable)
clock_t | clock (void)
time_t | time (void)
time_t | get_trusted_time (void)

Public Attributes
char | year
char | month
char | day
char | hour
char | minute
char | second
char | hundreds

Detailed Description

A time manipulation structure.

See also:
Time-related

Member Function Documentation

int Time_clear_alarm_flag ( void )

Resets the alarm flag.

Returns:
1 if alarm flag was set, 0 if not set, -1 if the flag could not be read
       #include <cybiko.h>
       ...
       // It's the same as using the Time_enable_alarm_int( FALSE ) function.
       // Turns off the alarm.
       Time_clear_alarm_flag();
       ...
       // Turns on the alarm.
       Time_enable_alarm_int( TRUE );
See also:
Time_enable_alarm_int.

void Time_decode ( | struct Time * ptr_time,
 | time_t time )

Decodes 'time' and fill fields.

Parameters:
ptr_time | A pointer to a Time object
time | The time_t format.
Returns:
None
       #include <cybiko.h>
       ...
       struct Time time;
       ...
       Time_decode( &time, last_key_time() );
       TRACE("Last key was pressed at hour: %d, minutes: %d, seconds: %d",
             time.hour,
             time.minute,
             time.second );
       ...
See also:
Time_encode.

bool Time_enable_alarm_int ( bool enable )

Sets or resets the alarm flag.

Parameters:
enable If TRUE, the alarm flag will be set, else will be reset
Returns:
The previous state of the alarm flag
       #include <cybiko.h>
       ...
       // It's the same as using the Time_enable_alarm_int( FALSE ) function.
       // Turns off the alarm.
       Time_clear_alarm_flag();
       ...
       // Turns on the alarm.
       Time_enable_alarm_int( TRUE );
See also:
Time_clear_alarm_flag.

time_t Time_encode ( struct Time * ptr_time )

Packs fields into the time_t type.

Parameters:
ptr_time A pointer to a Time object
Returns:
Packed field in the time_t type
       #include <cybiko.h>
       ...
       time_t packed_time;
       struct Time time;
       ...
       // 99 is 1999, 100 is 2000 and etc.
       time.year  = 100;
       time.month = 02;
       time.day = 07;
       time.hour = 22;
       time.minutes = 15;
       time.second = 15;
       time.hundreds = 10;
       ...
       packed_time = Time_encode( &time );
       ...
See also:
Time_decode , time_t.

bool Time_get_RTC ( struct Time * ptr_time )

Sets the fields according to the values read from the Real Time Clock (RTC).

Parameters:
ptr_time A pointer to a Time object
Returns:
TRUE if the field was set successfully
       #include <cybiko.h>
       ...
       struct Time time;
       Time_get_RTC( &time );
       time.hour++;
       time.hour %= 24;
       // We have changed the clock one hour ahead.
       Time_set_RTC( &time );
       ...

int Time_get_weekday ( struct Time * ptr_time )

Calculates the weekday for the current date (Sunday is 0, Saturday is 6).

Parameters:
ptr_time A pointer to a Time object
Returns:
The weekday number
       #include <cybiko.h>
       ...
       int week_day;
       struct Time time;
       ...
       Time_get_RTC( &time );
       ...
       week_day = Time_get_weekday( &time );
       ...

bool Time_set_RTC ( struct Time * ptr_time )

Sets the Real Time Clock (RTC) according to its fields.

Parameters:
ptr_time A pointer to a Time object
Returns:
TRUE if the time was set successfully
       #include <cybiko.h>
       ...
       struct Time time;
       Time_get_RTC( &time );
       time.hour++;
       time.hour %= 24;
       //  We have changed the clock one hour ahead.
       Time_set_RTC( &time );

Member Data Documentation

char day

Day of month, 1..31.

char hour

Hour, 0..23.

char hundreds

Hundredths of a second, 0..99.

char minute

Minute, 0..59.

char month

Month, 1..12.

char second

Second, 0..59.

char year

Year - 1900, 99 means 1999.


Sound, Music and Vibration

Defines
#define | CK_NO 0
#define | CK_BEEP 1
#define | CK_BEEP_SHORT 2
#define | BEEP_OK 0
#define | BEEP_INFO 1
#define | BEEP_QUESTION 2
#define | BEEP_ERROR 3

Functions
bool | get_sounds_enabled (void)
void | enable_sounds (bool enable)
void | beep (int beep_type)
bool | is_tone_playing (void)
void | play_tone (int index)
void | play_raw (int divisor)
void | stop_tone (void)
void | enable_vibration (bool enable)
void | vibrate (int index)

Compounds
struct MSequence The music sequence object

Detailed Description

These structures are used to control sound, music and vibration in the Cybiko computer. Most music control methods can be found within the description of the MSequence structure.

Define Documentation

#define BEEP_ERROR 3

The beep function argument for the ERROR dialog.

#define BEEP_INFO 1

The beep function argument for the INFO dialog.

#define BEEP_OK 0

The beep function argument for the OK dialog.

#define BEEP_QUESTION 2

The beep function argument for the QUESTION dialog.

#define CK_BEEP 1

Normal click sound.

#define CK_BEEP_SHORT 2

Short click sound.

#define CK_NO 0

No click sound.

Function Documentation

void beep ( int beep_type )

Produces a beep tone.

Parameters:
beep_type Is one of the following: BEEP_OK, BEEP_INFO, BEEP_QUESTION or BEEP_ERROR.
Returns:
None.
       #include <cybiko.h>
       ...
       beep( BEEP_QUESTION );
       ...
See also:
BEEP_OK, BEEP_INFO, BEEP_QUESTION, BEEP_ERROR.

void enable_sounds ( bool enable )

Enables or disables tone generation.
When tone generation is disabled, play_tone() has no effect (the device's speaker keeps silent). Tone generation is enabled on startup.

Parameters:
enable - If TRUE, tone generation is enabled, otherwise it is disabled.
Returns:
None.
       #include <cybiko.h>
       ...
       if ( !get_sounds_enabled() )
             enable_sounds( TRUE );
       ...

void enable_vibration ( bool enable )

Enables or disables vibration.

Parameters:
enable If TRUE, vibration will be enabled, else one will be disabled.
Returns:
None.
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       enable_vibration( TRUE );
       ...
       vibrate( 255 );
       cWinApp_pause( main_module.m_process, 250 );
       vibrate( 0 );
       ...
See also:
vibrate.

bool get_sounds_enabled ( void )

Returns a sounds-enabled flag state.

Returns:
Sounds-enabled flag state.
       #include <cybiko.h>
       ...
       if ( !get_sounds_enabled() )
             enable_sounds( TRUE );
       ...
See also:
enable_sounds.

bool is_tone_playing ( void )

Allows the device to determine whether or not a tone is being played.

Returns:
TRUE if a tone is being played, FALSE if no tone is being played.
       #include <cybiko.h>
       ...
       if ( !is_tone_playing() )
             beep( BEEP_ERROR );
       ...

void play_raw ( int divisor )

Starts playing a tone.
This function works the same way as the play_tone function. The difference is that, instead of the musical tone index, you provide the divisor for the timer so you can get any kind of sound this hardware can generate.

Parameters:
divisor Value from the range [6505 - 1356] (or 85Hz - 4075Hz )
Returns:
None.
       #include <cybiko.h>
       ...
       int index;
       int count = 0;
       ...
       // Here is a simple example that screams like a crazy cat:
       for( index = 0; index < 0xFFF; index++ )
       {
         count = ( count + 1 ) % 64;
         if( count < 32 )
             play_raw( count * 10 + 1000 );
         else
             play_raw( ( 64 - count ) * 10 + 1000 );
       }
       stop_tone();
See also:
play_tone.

void play_tone ( int index )

Starts tone generation.
The range of valid values is from 0 (85Hz) to 67 (about 4075Hz) inclusive. If the index is negative, calling play_tone() is the same as calling stop_tone().

Parameters:
index Specifies the frequency of the generated sound.
Returns:
None.
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone(30);
       cWinApp_pause(main_module.m_process, 200);
       play_tone(-1);
       ...
See also:
play_raw.

void stop_tone ( void )

Stops tone playing (turns the sound off).
It's safe to call it even if no tone is being played.

Returns:
None.
       #include <cybiko.h>
       ...
       int index;
       int count = 0;
       ...
       // Here is a simple example that screams like a crazy cat:
       for( index = 0; index < 0xFFF; index++ )
       {
         count = ( count + 1 ) % 64;
         if( count < 32 )
             play_raw( count * 10 + 1000 );
         else
             play_raw( ( 64 - count ) * 10 + 1000 );
       }
       stop_tone();
See also:
play_tone.

void vibrate ( int index )

Turns the vibrator on (if index > 0) or off (if index is 0).
The greater the index (0 .. 255), the stronger the vibrations.

Parameters:
index Strength of the vibration (0 .. 255). If index is 0, vibration will stop.
Returns:
None.
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       enable_vibration( TRUE );
       ...
       vibrate( 255 );
       cWinApp_pause( main_module.m_process, 250 );
       vibrate( 0 );
       ...
See also:
enable_vibration.


MSequence Struct Reference

Public Methods
struct MSequence* | MSequence_ctor (struct MSequence *ptr_msequence, char *sz_file_name)
bool | MSequence_is_sane (struct MSequence *ptr_msequence)
void | MSequence_play (struct MSequence *ptr_msequence)
void | MSequence_stop (struct MSequence *ptr_msequence)
bool | MSequence_is_playing (struct MSequence *ptr_msequence)
int | MSequence_get_curr_pos (struct MSequence *ptr_msequence)
bool | MSequence_load (struct MSequence *ptr_msequence, struct Input *ptr_input)
void | MSequence_dtor (struct MSequence *ptr_msequence, int memory_flag)
void | MSequence_play_background (struct MSequence *ptr_msequence)
void | MSequence_global_mute (bool mute_flag)
void | MSequence_mute_foreground (bool mute_flag)
void | MSequence_mute_background (bool mute_flag)

Detailed Description

The music sequence object. Allows the end user to manipulate the music-playing on Cybiko computers. You must call MSequence_ctor before use and MSequence_dtor after use.

See also:
MSequence_ctor, MSequence_dtor, Sound, Music and Vibration

Member Function Documentation

struct MSequence * MSequence_ctor ( | struct MSequence * ptr_msequence,
 | char * sz_file_name )

Creates a music sequence from a specified resource (file) name.

Parameters:
ptr_msequence | A pointer to a MSequence structure.
sz_file_name | The music seqence's resource file name (*.mus)
Returns:
A pointer to the initialized music sequence
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_dtor ( | struct MSequence * ptr_msequence,
 | int memory_flag )

Destructor.
Performs cleanup.

Parameters:
ptr_msequence | A pointer to the initialized music sequence.
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int MSequence_get_curr_pos ( struct MSequence * ptr_msequence )

Returns the current position (0xFFFF if it's about to start playing the first event).

Parameters:
ptr_msequence A pointer to the initialized music sequence
Returns:
The current position
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music in the first of 20 music events.
       if( MSequence_get_curr_pos ( &intro_music ) > 20 )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_global_mute ( bool mute_flag )

Sets or clears the global mute flag.

Parameters:
mute_flag If TRUE all sounds will be disabled; otherwise enabled
Returns:
None
       #include <cybiko.h>
       ...
       // Turns off music at all.
       MSequence_global_mute( TRUE );
       ...
       // Turns on music again.
       MSequence_global_mute( FALSE );
       ...

bool MSequence_is_playing ( struct MSequence * ptr_msequence )

Checks whether a music sequence is playing.

Parameters:
ptr_msequence A pointer to the initialized music sequence
Returns:
TRUE if music is playing
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

bool MSequence_is_sane ( struct MSequence * ptr_msequence )

Checks whether the current content appears to be valid.

Parameters:
ptr_msequence A pointer to the initialized music sequence
Returns:
TRUE if the content is valid
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

bool MSequence_load ( | struct MSequence * ptr_msequence,
 | struct Input * ptr_input )

Loads a sequence from a specified Input stream.

Parameters:
ptr_msequence | A pointer to the initialized music sequence
ptr_input | A pointer to the Input stream structure of an opened music resource
Returns:
TRUE if initialization succeeded
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       struct Input* ptr_input;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       ptr_input = open_recourse_Ex( "new_intro.mus" );
       MSequence_load( &intro_music, ptr_input );
       if( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

void MSequence_mute_background ( bool mute_flag )

Sets or clears the background music(effects) mute flag.

Parameters:
mute_flag If TRUE background sounds will be disabled; otherwise enabled
Returns:
None
       #include <cybiko.h>
       ...
       // Turns off background sound.
       MSequence_mute_background( TRUE );
       ...
       // Turns on background sound again.
       MSequence_mute_background( FALSE );
       ...

void MSequence_mute_foreground ( bool mute_flag )

Sets or clears the foreground music(effects) mute flag.

Parameters:
mute_flag If TRUE, foreground sounds will be disabled; otherwise enabled
Returns:
None
       #include <cybiko.h>
       ...
       //  Turns off sound effects.
       MSequence_mute_foreground( TRUE );
       ...
       //  Turns on sound effects again.
       MSequence_mute_foreground( FALSE );
       ...

void MSequence_play ( struct MSequence * ptr_msequence )

Plays a music sequence in the foreground.

Parameters:
ptr_msequence A pointer to the initialized music sequence.
Returns:
None
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if ( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_play_background ( struct MSequence * ptr_msequence )

Plays the a music sequence in the background.

Parameters:
ptr_msequence A pointer to the initialized music sequence.
Returns:
None
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if ( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Loops background music.
       if( !MSequence_is_playing ( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...

void MSequence_stop ( struct MSequence * ptr_msequence )

Stops playing a music sequence.

Parameters:
ptr_msequence A pointer to the initialized music sequence.
Returns:
None
       #include <cybiko.h>
       ...
       struct MSequence intro_music;
       ...
       MSequence_ctor( &intro_music, "intro.mus" );
       ...
       if ( MSequence_is_scene( &intro_music ) )
       {
         MSequence_play_background( &intro_music );
       }
       ...
       // Stops background music.
       if( MSequence_is_playing ( &intro_music ) )
       {
         MSequence_stop( &intro_music );
       }
       ...
       MSequence_dtor( &intro_music, LEAVE_MEMORY );
       ...


Messaging

Defines
#define | MSG_AUTODELETE 0x80000000
#define | MSG_MAX_TIMEOUT 0x0FFFFFFF
#define | MSG_KEYMIN 1
#define | MSG_KEYDOWN 1
#define | MSG_KEYUP 2
#define | MSG_CHARTYPED 3
#define | MSG_TIMER 0x20
#define | MSG_POWERDOWN 0x30
#define | MSG_QUIT 0x31
#define | MSG_PAINT 0x32
#define | MSG_FILES 0x33
#define | MSG_LOSTFOCUS 0x40
#define | MSG_GOTFOCUS 0x41
#define | MSG_LAUNCH 0x42
#define | MSG_DEVICE 0x43
#define | MSG_PING 0x44
#define | MSG_SHUTUP 0x101A
#define | MSG_USER 0x2000
#define | DL_NONE 0
#define | DL_INQUEUE 1
#define | DL_WAIT 2
#define | DL_ABORT 3
#define | DL_TIMEOUT 4
#define | DL_SUCCESS 5
#define | MSG_USER_FOLK 0x1001

Typedefs
typedef long | cyid_t
typedef int | delivery_t

Enumerations
enum qflag_t {
QF_NONE = 0,
QF_DEVICES = 1,
QF_FILES = 2,
QF_APPMASK = 0x1000,
QF_ALL = 0xffff
}
enum keymask_t {
KEYMASK_SHIFT = 0x0001,
KEYMASK_CTRL = 0x0002,
KEYMASK_AUTOREPEAT = 0x0004
}

Functions
char | howmany_around_desktop (void)
bool | send_msg (char *app_name, int msgid, long d0, long d1, void *data, size_t size)
bool | send_copy_msg (char *app_name, struct Message *msg)
bool | send_remote_msg (cyid_t cyid, char *app_name, int msgid, long d0, long d1, void *data, size_t size)
bool | send_remote_copy_msg (cyid_t cyid, char *app_name, struct Message *msg)
bool | send_msg_launch (char *app_name)
cyid_t | get_own_id (void)

Compounds
struct | Buffer | A dynamic memory buffer
struct | KeyParam | The parameter holder for keyboard messages
struct | Message | Structure for interprocess communications; can be sent either locally or remotely

Detailed Description

These functions and structures are used to send messages between applications, including those running on different Cybiko computers. You may also want to examine the Message and Buffer structures.

Define Documentation

#define DL_ABORT 3

Message delivery aborted by internal error or user request.

#define DL_INQUEUE 1

Message is in queue to deliver; please, don't delete the message while in this state.

#define DL_NONE 0

Message was created and possibly posted.

#define DL_SUCCESS 5

Message was delivered successfully.

#define DL_TIMEOUT 4

Message delivery finished by timeout.

#define DL_WAIT 2

Message is being delivered.

#define MSG_AUTODELETE 0x80000000

Message_deliver() flag, which deletes the message after it was delivered.

#define MSG_CHARTYPED 3

Sends the message to the focused program when the user releases a key.

#define MSG_DEVICE 0x43

Receiver sends the message when a device appears or disappears on the channel.

#define MSG_FILES 0x33

Lists changes in the file system.

#define MSG_GOTFOCUS 0x41

The process gets the message once it gets the focus.

#define MSG_KEYDOWN 1

Sends the message to the focused program when the user presses a key.

#define MSG_KEYMIN 1

Minimum ID of a keyboard message.

#define MSG_KEYUP 2

Sends the message to the focused program when the user releases a key.

#define MSG_LAUNCH 0x42

Sends the message to the Process you want to launch.

#define MSG_LOSTFOCUS 0x40

The Process gets the message when it loses focus.

#define MSG_MAX_TIMEOUT 0x0FFFFFFF

Message_deliver() maximum timeout.

#define MSG_PAINT 0x32

About repaint.

#define MSG_PING 0x44

Message is sent by the Receiver to ping the listener process.

#define MSG_POWERDOWN 0x30

Batteries are low, warn the user !

#define MSG_QUIT 0x31

Sends this message when the process should finish.

#define MSG_SHUTUP 0x101A

Process must be terminated.

#define MSG_TIMER 0x20

Sent when the pre-set timer counts down to 0.

#define MSG_USER 0x2000

Start of the user_defined message ID.

#define MSG_USER_FOLK 0x1001

ID of the message sent to the application when any device appears or disappears from the environment.

Typedef Documentation

typedef long cyid_t

Device's Cy ID.

typedef int delivery_t

Message delivery state.
Must be one of the following: DL_NONE, DL_INQUEUE, DL_WAIT, DL_ABORT, DL_TIMEOUT or DL_SUCCESS.

See also:
DL_NONE, DL_INQUEUE, DL_WAIT, DL_ABORT, DL_TIMEOUT, DL_SUCCESS.

Enumeration Type Documentation

enum keymask_t

Keyboard modificators masks.

Enumeration values:
KEYMASK_SHIFT | Shift was pressed.
KEYMASK_CTRL | Control was pressed.
KEYMASK_AUTOREPEAT | It is autorepeat-generated message (not the first key down).

enum qflag_t

Enumeration of masks for local broadcast messages.

Enumeration values:
QF_NONE | Queue will get only messages for QF_NONE.
QF_DEVICES | Queue will get only messages for unit changes.
QF_FILES | Queue will get only messages for file system changes.
QF_APPMASK | First value for application masks.
QF_ALL | Mask for all MASKED queues.

Function Documentation

cyid_t get_own_id ( void )

Returns device's CyID.

Returns:
Device's CyID
       #include <cywin.h>
       ...
       #define MSG_TEST     MSG_USER + 1
       ...
       struct Message* ptr_message = Message_new( sizeof( struct Message ) );
       ptr_message->msgid = MSG_TEST;
       // Sends the message to the 'data_receiver' process on the same device.
       Message_post( ptr_message, "data_receiver", get_own_id() );
       ...

char howmany_around_desktop ( void )

Returns the number of other users in the vicinity, with maximum activity.

Returns:
Number of Cybiko devices the finder detects
       #include <cybiko.h>
       ...
       TRACE("Active people: %d", finder.howmany_around);
       TRACE("Around desktop: %d", howmany_around_desktop());
       ...

bool send_copy_msg ( | char * app_name,
 | struct Message * msg )

Sends a pre-written message to another application in the same Cybiko computer.

Parameters:
app_name | The name of the application to which the message is addressed
msg | Pointer to the pre-written message to be sent in Message structure
Returns:
1, if message was sent successfully, 0 otherwise

bool send_msg ( | char * app_name,
 | int msgid,
 | long d0,
 | long d1,
 | void * data,
 | size_t size )

Sends a message to another application in the same Cybiko computer.

Parameters:
app_name | The name of the application to which the message is addressed
msgid | Message identifier
d0 | The message's 1st additional parameter (default value - 0)
d1 | The message's 2nd additional parameter of message (default value - 0)
data | Pointer to message-related data (default value - 0)
size | Size of related data (default value - 0)
Returns:
1, if message was sent successfully, 0 otherwise

bool send_msg_launch ( char * app_name )

Launches the 'app_name' application.

Parameters:
app_name Name of the application to be launched
Returns:
1, if message was sent successfully, 0 otherwise

bool send_remote_copy_msg ( | cyid_t cyid,
 | char * app_name,
 | struct Message * msg )

Sends pre-written message to another application in the same or other Cybiko computer.

Parameters:
cyid | CyID of the Cybiko computer to which the message is addressed
app_name | The name of the application to which the message is addressed
msg | Pointer to the pre-written message to be sent in Message structure
Returns:
1, if message was sent successfully, 0 otherwise

bool send_remote_msg ( | cyid_t cyid,
 | char * app_name,
 | int msgid,
 | long d0,
 | long d1,
 | void * data,
 | size_t size )

Sends message to another application in the same or another Cybiko computer.

Parameters:
cy_id | CyID of the Cybiko computer to which the message is addressed
app_name | The name of the application to which the message is addressed
msgid | Message identifier
d0 | The message's 1st additional parameter (default value - 0)
d1 | The message's 2nd additional parameter (default value - 0)
data | Pointer to message-related data (default value - 0)
size | Size of related data (default value - 0)
Returns:
1, if message was sent successfully, 0 otherwise


Buffer Struct Reference

Public Methods
struct Buffer* | Buffer_ctor (struct Buffer *ptr_buffer, size_t size, size_t increment)
struct Buffer* | Buffer_ctor_Ex (struct Buffer *ptr_buffer, struct Buffer *templ)
void | Buffer_store (struct Buffer *ptr_buffer, void *ptr_data, size_t offset, size_t length)
void | Buffer_store_string (struct Buffer *ptr_buffer, char *str, size_t offset)
void* | Buffer_load (struct Buffer *ptr_buffer, void *ptr_data, size_t offset, size_t length)
char* | Buffer_load_string (struct Buffer *ptr_buffer, char *str, size_t offset, size_t length)
size_t | Buffer_get_size (struct Buffer *ptr_buffer)
size_t | Buffer_get_allocated_size (struct Buffer *ptr_buffer)
void | Buffer_compact (struct Buffer *ptr_buffer)
bool | Buffer_set_size (struct Buffer *ptr_buffer, size_t size)
void | Buffer_free (struct Buffer *ptr_buffer)
bool | Buffer_ensure_size (struct Buffer *ptr_buffer, size_t test_size)
char | Buffer_get_char (struct Buffer *ptr_buffer, size_t offset)
void | Buffer_set_char (struct Buffer *ptr_buffer, size_t offset, char data)
int | Buffer_get_int (struct Buffer *ptr_buffer, size_t offset)
void | Buffer_set_int (struct Buffer *ptr_buffer, size_t offset, int data)
long | Buffer_get_long (struct Buffer *ptr_buffer, size_t offset)
void | Buffer_set_long (struct Buffer *ptr_buffer, size_t offset, long data)
bool | Buffer_is_locked (struct Buffer *ptr_buffer)
void* | Buffer_lock (struct Buffer *ptr_buffer)
void | Buffer_unlock (struct Buffer *ptr_buffer)
void | Buffer_dtor (struct Buffer *ptr_buffer, int)

Detailed Description

This object provides a movable memory buffer that can be dynamically created, resized, and used as a plain memory block or as storage with access helpers.

For CyOS, buffers are better than plain dynamic memory - allocated chunks because they can be locked and unlocked. While they are unlocked, the OS may move them in order to organize memory more efficiently, and may even drop the buffer to the flash so it may be used as a kind of virtual memory.

The best way to work with this object is to keep the buffer unlocked and use access helpers methods Buffer_load, Buffer_load_string, Buffer_store, Buffer_store_string, Buffer_get_byte, Buffer_set_byte, Buffer_get_char, Buffer_set_char, Buffer_get_int, Buffer_set_int, Buffer_get_long, Buffer_set_long and so on.

The difference between store_ and set_ methods is that store_* automatically resizes the buffer to fit the size required, while set_ methods check and treat " out of bounds " as an error.

Please note that the offsets for all helpers get_* and set_* are ALWAYS IN BYTES. The Buffers have a size/increment/capacity space strategy. This means that when a Buffer needs to expand its storage, it uses an increment and stores both the actual data size and the current capacity to minimize the load on the dynamic memory subsystem.

Use Buffer_set_size, Buffer_ensure_size and Buffer_compact methods to manage the buffer's capacity.

See also:
Messaging

Member Function Documentation

void Buffer_compact ( struct Buffer * ptr_buffer )

Resizes storage to the current data size.

Parameters:
ptr_buffer A pointer to the initialized Buffer object
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[120];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 120 );
       ...
       Buffer_compact( &buffer );
       // The real_size value will be equal to 120.
       // Without calling the Buffer_compact function
       // the real_size value will be equal to 1024.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 120 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

struct Buffer * Buffer_ctor ( | struct Buffer * ptr_buffer,
 | size_t size,
 | size_t increment )

Create an empty buffer of a specified data_size.

Parameters:
ptr_buffer | A pointer to the Buffer structure
size | The initial buffer size
increment | An increment value
Returns:
A pointer to the initialized Buffer object
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int index;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       for( index = 0; strlen( sz_string_array[index] ); index++ )
       {
         Buffer_store_string( &buffer, sz_string_array[index],
                              Buffer_get_size( &buffer ) );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_ctor_Ex.

struct Buffer * Buffer_ctor_Ex ( | struct Buffer * ptr_buffer,
 | struct Buffer * templ )

Creates a copy of the existing buffer.

Parameters:
ptr_buffer | A pointer to the Buffer structure
templ | A pointer to the template Buffer object
Returns:
A pointer to the initialized Buffer object
       #include <cywin.h>
       ...
       struct Buffer buffer;
       struct Buffer buffer_tmpl;
       int index;
       ...
       Buffer_ctor( &buffer_tmpl, 1024, 64 );
       ...
       for( index = 0; strlen( sz_string_array[index] ); index++ )
       {
         Buffer_store_string( &buffer_templ, sz_string_array[index],
                                Buffer_get_size( &buffer_templ ) );
       }
       ...
       Buffer_ctor_Ex( &buffer, &buffer_templ );
       ...
       Buffer_dtor( &buffer_templ, LEAVE_MEMORY );
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_ctor.

void Buffer_dtor ( | struct Buffer * ptr_buffer,
 | int memory_flag )

Unlocks and frees a previously locked buffer.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in stack
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[120];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 120 );
       ...
       Buffer_compact( &buffer );
       // The real_size value will be equal to 120.
       // Without calling the Buffer_compact function
       // the real_size value will be equal to 1024.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 120 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool Buffer_ensure_size ( | struct Buffer * ptr_buffer,
 | size_t test_size )

Reallocates and copies the buffer's contents, if needed.
Make sure the buffer's storage is not less than test_size

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
test_size | The size of the Buffer to test
Returns:
TRUE if the buffer has suffiicient capacity, FALSE if enough space can not be allocated to fit the specified size
       #include <cywin.h>
       ...
       struct Buffer buffer;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Frees the buffer and allocates a new buffer size.
       Buffer_free( &buffer );
       if ( Buffer_ensure_size( &buffer, 10000 ) )
       {
          Buffer_set_size( &buffer, 10000 );
          ...
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

void Buffer_free ( struct Buffer * ptr_buffer )

Clears the buffer and frees its storage.

Parameters:
ptr_buffer A pointer to the initialized Buffer object
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Frees the buffer and allocates a new buffer size.
       Buffer_free( &buffer );
       Buffer_set_size( &buffer, 120 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

size_t Buffer_get_allocated_size ( struct Buffer * ptr_buffer )

Returns the size of the allocated space (current capacity that may be bigger than Buffer_get_size()).

Parameters:
ptr_buffer A pointer to the initialized Buffer object
Returns:
Size of the allocated space
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[120];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 120 );
       ...
       // The real_size value will be equal to 1024.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 120 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_size.

char Buffer_get_char ( | struct Buffer * ptr_buffer,
 | size_t offset )

Reads char at the specified 'offset'.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
offset | The offset in the buffer
Returns:
Char was read
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char   read_byte;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes the byte 'y ' at the 12th position in the buffer.
       Buffer_set_byte( &buffer, 12, 'y ' );
       ...
       // Reads a byte at the 12th position in the buffer.
       read_byte = Buffer_get_byte( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_set_char.

int Buffer_get_int ( | struct Buffer * ptr_buffer,
 | size_t offset )

Reads the int value at the specified 'offset'.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
offset | The offset in the buffer
Returns:
Int value was read
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int    read_int;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_int( &buffer, 12, 120 );
       ...
       // Reads a value at the 12th position in the buffer.
       read_int = Buffer_get_int( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_set_int.

long Buffer_get_long ( | struct Buffer * ptr_buffer,
 | size_t offset )

Reads the long value at the specified 'offset'.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
offset | The offset in the buffer
Returns:
Long value was read
       #include <cywin.h>
       ...
       struct Buffer buffer;
       long   read_long;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_long( &buffer, 12, 0x7FFFFFFF );
       ...
       // Reads a value at the 12th position in the buffer.
       read_long = Buffer_get_long( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_set_long.

size_t Buffer_get_size ( struct Buffer * ptr_buffer )

Returns the size of the data in the buffer.

Parameters:
ptr_buffer A pointer to the initialized Buffer object
Returns:
The size of the data in the buffer
       #include <cywin.h>
       #define MAX_STRING_LENGTH 64
       ...
       struct Buffer buffer;
       int string_number;
       int index;
       int offset = 0;
       char sz_text_buffer[MAX_STRING_LENGTH];
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores strings.
       for( string_number = 0; strlen( sz_string_array[string_number] ); string_number++ )
       {
         Buffer_store_string( &buffer, sz_string_array[string_number],
                                Buffer_get_size( &buffer ) );
       }
       ...
       //  Trace strings.
       for( index = 0; index < string_number; index++ )
       {
         Buffer_load_string( &buffer, sz_text_buffer, offset, 0 );
         offset += strlen() + 1;
         TRACE( "%i string is %s", index, sz_text_buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_allocated_size, Buffer_set_size.

bool Buffer_is_locked ( struct Buffer * ptr_buffer )

Returns lock state (locked or unlocked).

Parameters:
ptr_buffer A pointer to the initialized Buffer object
Returns:
TRUE, if the buffer is locked, FALSE otherwise
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* ptr_pure_data;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       ptr_pure_data = Buffer_lock( &buffer );
       ptr_pure_data[12] = 'y ';
       ...
       if( Buffer_is_locked( &buffer ) )
       {
         Buffer_unlock( &buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_lock.

void * Buffer_load ( | struct Buffer * ptr_buffer,
 | void * ptr_data,
 | size_t offset,
 | size_t length )

Loads 'length' bytes from the Buffer, starting at the specified 'offset'.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
ptr_data | Where to store the loaded bytes
offset | The point at which to start copying bytes
length | How many bytes to copy; if 0 then all data size is supposed
Returns:
A pointer for convenience and style reasons
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[120];
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 120 );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 120 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_load_string.

char * Buffer_load_string ( | struct Buffer * ptr_buffer,
 | char * str,
 | size_t offset,
 | size_t length )

Loads null terminated string.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
str | Where to store the string
offset | The offset in the buffer
length | The maximum length of the string; if 0 then all data size is supposed
Returns:
A pointer to the string
       #include <cywin.h>
       #define MAX_STRING_LENGTH 64
       ...
       struct Buffer buffer;
       int string_number;
       int index;
       int offset = 0;
       char sz_text_buffer[MAX_STRING_LENGTH];
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores strings.
       for( string_number = 0; strlen( sz_string_array[string_number] ); string_number++ )
       {
         Buffer_store_string( &buffer, sz_string_array[string_number],
                              Buffer_get_size( &buffer ) );
       }
       ...
       //  Trace strings.
       for( index = 0; index < string_number; index++ )
       {
         Buffer_load_string( &buffer, sz_text_buffer, offset, 0 );
         offset += strlen() + 1;
         TRACE( "%i string is %s", index, sz_text_buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_load.

void * Buffer_lock ( struct Buffer * ptr_buffer )

Locks storage and returns the pointer to it's area.
Note that a locked buffer can not be trashed. Be very careful with this pointer and do not access more data than the number of Buffer_get_size() bytes. Do not use this pointer after Buffer_unlock() was called.

Parameters:
ptr_buffer A pointer to the initialized Buffer object
Returns:
Address of the locked buffer's data area
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* ptr_pure_data;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       ptr_pure_data = Buffer_lock( &buffer );
       ptr_pure_data[12] = 'y';
       ...
       if( Buffer_is_locked( &buffer ) )
       {
         Buffer_unlock( &buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_unlock, Buffer_is_locked.

void Buffer_set_char ( | struct Buffer * ptr_buffer,
 | size_t offset,
 | char data )

Writes char value 'data' at the specified 'offset'.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
offset | The offset in the buffer
data | The character to set
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char   read_byte;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes the byte 'y' at the 12th position in the buffer.
       Buffer_set_byte( &buffer, 12, 'y' );
       ...
       // Reads a byte at the 12th position in the buffer.
       read_byte = Buffer_get_byte( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_char.

void Buffer_set_int ( | struct Buffer * ptr_buffer,
 | size_t offset,
 | int data )

Writes the int 'data' at the specified 'offset'.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
offset | The offset in the buffer
data | The int to set
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int    read_int;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_int( &buffer, 12, 120 );
       ...
       // Reads a value at the 12th position in the buffer.
       read_int = Buffer_get_int( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_int.

void Buffer_set_long ( | struct Buffer * ptr_buffer,
 | size_t offset,
 | long data )

Writes the long value 'data' at the specified 'offset'.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object.
offset | The offset in the buffer
data | The long to set
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       long   read_long;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       // Writes a value at the 12th position in the buffer.
       Buffer_set_long( &buffer, 12, 0x7FFFFFFF );
       ...
       // Reads a value at the 12th position in the buffer.
       read_long = Buffer_get_long( &buffer, 12 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_long.

bool Buffer_set_size ( | struct Buffer * ptr_buffer,
 | size_t size )

Sets the size.
If the size requested is less than the current capacity, extra space might be freed for the OS.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
size | The new buffer size
Returns:
TRUE if the buffer size is changed successfully
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* some_data[120];
       int real_size;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       //  Stores data;
       Buffer_store( &buffer, &some_data, 0, 120 );
       ...
       Buffer_set_size( &buffer, 120 );
       // The real_size value will be equal to 120.
       real_size = Buffer_get_allocated_size( &buffer );
       ...
       //  Loads data;
       Buffer_load( &buffer, &some_data, 0, 120 );
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_get_size.

void Buffer_store ( | struct Buffer * ptr_buffer,
 | void * ptr_data,
 | size_t offset,
 | size_t length )

Stores some data at the specified offset.
If needed, the buffer will expand it's storage to fit the specified 'length' of the data.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
ptr_data | A pointer to the data to store
offset | The offset in the buffer
length | The data's length; if it sets to 0 then the current size of the buffer will be used
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int index;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       for( index = 0; strlen( sz_string_array[index]); index++ )
       {
         Buffer_store( &buffer,
                       sz_string_array[index],
                       Buffer_get_size( &buffer ),
                       strlen( sz_string_array[index] ) + 1 );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

void Buffer_store_string ( | struct Buffer * ptr_buffer,
 | char * str,
 | size_t offset )

Stores a null-terminated string into the buffer.
If needed, buffer will extend it's storage to fit the data's specified length.

Parameters:
ptr_buffer | A pointer to the initialized Buffer object
str | The string to store
offset | The offset in the buffer
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       int index;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       for( index = 0; strlen( sz_string_array[index] ); index++ )
       {
         Buffer_store_string( &buffer, sz_string_array[index],
                              Buffer_get_size( &buffer ) );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...

void Buffer_unlock ( struct Buffer * ptr_buffer )

Unlocks the buffer's storage.
Note that all references to the buffer area returned by Buffer_lock() become invalid and very dangerous to use; you can destroy the system very easily by using this pointer after Buffer_unlock().

Parameters:
ptr_buffer A pointer to the initialized Buffer object
Returns:
None
       #include <cywin.h>
       ...
       struct Buffer buffer;
       char* ptr_pure_data;
       ...
       Buffer_ctor( &buffer, 1024, 64 );
       ...
       ptr_pure_data = Buffer_lock( &buffer );
       ptr_pure_data[12] = 'y';
       ...
       if( Buffer_is_locked( &buffer ) )
       {
         Buffer_unlock( &buffer );
       }
       ...
       Buffer_dtor( &buffer, LEAVE_MEMORY );
       ...
See also:
Buffer_lock.


KeyParam Struct Reference

Public Attributes
int | scancode
int | mask
char | ch

Detailed Description

The parameter holder for keyboard messages.

See also:
Messaging

Member Data Documentation

char ch

Character read from the keyboard.

int mask

Keyboard modifier mask.

int scancode

Keyboard virtual keys code.


Message Struct Reference

Collaboration diagram for Message:

Public Methods
struct KeyParam* | Message_get_key_param (struct Message *ptr_message)
struct Message* | Message_new (size_t sizeof_message)
cyid_t | Message_get_sender_id (struct Message *ptr_message)
bool | Message_is_broadcast (struct Message *ptr_message)
bool | Message_post (struct Message *ptr_message, char *sz_process_name, cyid_t cyid)
void | Message_post_all (struct Message *ptr_message, short mask)
void* | Message_deliver (struct Message *ptr_message, char *sz_process_name, cyid_t cyid, clock_t timeout)
delivery_t | Message_check_delivery (struct Message *ptr_message)
delivery_t | Message_wait_delivery (struct Message *ptr_message, struct Flag *ptr_flag)
bool | Message_has_buffer (struct Message *ptr_message)
struct Buffer* | Message_get_buffer (struct Message *ptr_message)
void | Message_attach_buffer (struct Message *ptr_message, struct Buffer *ptr_buffer)
void | Message_copy (struct Message *ptr_message, struct Message *ptr_templ)
void | Message_delete (struct Message *ptr_message)

Public Attributes
struct Message* | next
char* | dst_name
cyid_t cyid_from
cyid_t cyid_to
bool | deleted
short | msgid
long | param [2]

Detailed Description

Structure for interprocess communications; can be sent either locally or remotely.

See also:
Messaging

Member Function Documentation

void Message_attach_buffer ( | struct Message * ptr_message,
 | struct Buffer * ptr_buffer )

Attaches a buffer to the message.
Note: the Buffer recycles automatically along with the Message.

Parameters:
ptr_message | A pointer to the initialized Message object
ptr_buffer | A pointer to the initialized Buffer object to attach
Returns:
None
       #include <cybiko.h>
       #define MSG_CHAT_STRING     MSG_USER + 1
       ...
       struct module_t main_module;
       struct Buffer message_buffer;
       char partner_name[9];
       cyid_t partner_id;
       ...
       init_module( &main_module );
       ...
       partner_id = select_game_partner( main_module.m_process,
                                         "Billiard",
                                         SGP_CYBIKO | SGP_HOT_SEAT,
                                         partner_name );
       if( partner_id )
       {
         ...
         struct Message* ptr_message = Message_new( sizeof( struct Message ) );
         ptr_message->msgid = MSG_CHAT_STRING;
         Buffer_ctor( &message_buffer, 20, 10 );
         Buffer_store_string( &message_buffer, "Hey, dude!", 0 );
         Message_attach_buffer( ptr_message, &message_buffer );
         Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
       }
       ...

delivery_t Message_check_delivery ( struct Message * ptr_message )

Checks the delivery state.

Parameters:
ptr_message A pointer to the initialized Message object
Returns:
Delivery state
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct module_t main_module;
       char partner_name[9];
       cyid_t partner_id;
       delivery_t delivery_result;
       ...
       init_module( &main_module );
       ...
       partner_id = select_game_partner( main_module.m_process,
                                         "Billiard",
                                         SGP_CYBIKO | SGP_HOT_SEAT,
                                         partner_name );
       if( partner_id )
       {
         ...
         struct Message* ptr_message = Message_new( sizeof( struct Message ) );
         ptr_message->msgid = MSG_TEST;
         //  Sends message to "Billiard" application on the remote computer.
         Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
       }

       while(1)
       {
         cWinApp_pause( module.m_process, 250 );
         delivery_result = Message_check_delivery( ptr_test_message );
         if( delivery_result == DL_SUCCESS )
         {
           TRACE( "Message was delivered successfully" );
           break;
         }
         else if( ( delivery_result == DL_ABORT )
                  || ( delivery_result == DL_TIMEOUT ) )
         {
           TRACE( "Message was not delivered successfully" );
           break;
         }
       }
       ...
See also:
DL_INQUEUE, DL_WAIT, DL_ABORT, DL_TIMEOUT, DL_SUCCESS.

void Message_copy ( | struct Message * ptr_message,
 | struct Message * ptr_templ )

Makes the destination Message an exact copy of the source Message.

Parameters:
ptr_message | A pointer to the destination Message object
ptr_templ | A pointer to the source Message object
Returns:
None
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct Message* ptr_message = Message_new( sizeof( struct Message ) );
       struct Message* ptr_message_repeat = Message_new( sizeof( struct Message ) );
       ptr_message->msgid = MSG_TEST;
       ...
       Message_copy( ptr_message_repeat, ptr_message );
       // Sends the message to the 'data_reciever' process which
       // is on the same device.
       Message_post( ptr_message, "data_reciever", get_own_id() );
       //  Repeats message.
       Message_post( ptr_message_repeat, "data_reciever", get_own_id() );
       ...

void Message_delete ( struct Message * ptr_message )

Deletes a message.

Parameters:
ptr_message A pointer to the initialized Message object
Returns:
None
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct Message* ptr_message = Message_new( sizeof( struct Message ) );
       ptr_message->msgid = MSG_TEST;
       //  Sends the message to the 'data_reciever' process which
       //  is on the same computer.
       Message_post( ptr_message, "data_reciever", get_own_id() );
       ...

void * Message_deliver ( | struct Message * ptr_message,
 | char * sz_process_name,
 | cyid_t cyid,
 | clock_t timeout )

Delivers a message to a specified target, with delivery result notification.

Parameters:
ptr_message | A pointer to the initialized Message object
sz_process_name | The target process' name
cyid | The target device's Cy ID
timeout | A special time to wait. If the Message is not delivered to the target during the timeout, then the delivery state becomes DL_TIMEOUT
Returns:
None
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct module_t main_module;
       struct Flag delivery_flag;
       char partner_name[9];
       cyid_t partner_id;
       ...
       init_module( &main_module );
       ...
       partner_id = select_game_partner( main_module.m_process,
                                         "Billiard",
                                         SGP_CYBIKO | SGP_HOT_SEAT,
                                         partner_name );
       if( partner_id )
       {
         ...
         struct Message* ptr_message = Message_new( sizeof( struct Message ) );
         ptr_message->msgid = MSG_TEST;
         //  Sends message to the "Billiard" application on the remote computer.
         Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
       }
       Flag_ctor(&delivery_flag, "MessageMutex", TRUE);
       if( Message_wait_delivery( ptr_message, &delivery_flag ) == DL_SUCCESS )
       {
         TRACE( "Message was delivered successfully" );
       }
       Flag_dtor(&delivery_flag, LEAVE_MEMORY);
       ...

struct Buffer * Message_get_buffer ( struct Message * ptr_message )

Gets a pointer to the attached buffer.
Note, the Buffer created by the system when that receives the message will recycle automatically along with the Message.

Parameters:
ptr_message A pointer to the initialized Message object
Returns:
A pointer to the Buffer object
       #include <cybiko.h>
       #define MSG_CHAT_STRING     MSG_USER + 1
       ...
       struct module_t main_module;
       char sz_string_text[32];
       ...
       init_module( &main_module );
       ...
       struct Message* ptr_message = cWinApp_get_message( main_module.m_process,
                                                          0,
                                                          1,
                                                          MSG_CHAT_STRING );
       if( ptr_message->msgid == MSG_CHAT_STRING )
       {
         if( Message_has_buffer( ptr_message ) )
         {
            Buffer_load( Message_get_buffer( ptr_message ),
                         sz_string_text,
                         0,
                         0 );
            TRACE( "Message from the opponent: %s", sz_string_text );
         }
       }
       ...
See also:
Message_has_buffer.

struct KeyParam * Message_get_key_param ( struct Message * ptr_message )

Returns a pointer to the message's KeyParam structure.

Parameters:
ptr_message A pointer to the initialized Message object
Returns:
A pointer to the KeyParam structure of the message
       #include <cybiko.h>
       ...
       struct module_t  main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = cWinApp_get_message( main_module.m_process,
                                          0,
                                          1,
                                          MSG_USER );
       if( ptr_message->msgid == MSG_KEYDOWN )
       {
         if( Message_get_key_param( ptr_message )->scancode == MSG_ESC )
         {
           //  Processes key 'Esc'.
         }
       }
       ...

cyid_t Message_get_sender_id ( struct Message * ptr_message )

Returns the 32-bit device ID (CyID) of the Message's sender.

Parameters:
ptr_message A pointer to the initialized Message object
Returns:
The 32-bit device ID (CyID) of the Message's sender

bool Message_has_buffer (

struct Message * ptr_message )

Tests whether the Message has an attached buffer.

Parameters:

ptr_message

 A pointer to the initialized Message object

Returns:

 TRUE if the message has a buffer
       #include <cybiko.h>
       #define MSG_CHAT_STRING     MSG_USER + 1
       ...
       struct module_t main_module;
       char sz_string_text[32];
       ...
       init_module( &main_module );
       ...
       struct Message* ptr_message = cWinApp_get_message( main_module.m_process,
                                                          0,
                                                          1,
                                                          MSG_CHAT_STRING );
       if( ptr_message->msgid == MSG_CHAT_STRING )
       {
         if( Message_has_buffer( ptr_message ) )
         {
            Buffer_load( Message_get_buffer( ptr_message ),
                         sz_string_text ,
                         0,
                         0 );
            TRACE( "Message from the opponent: %s", sz_string_text );
         }
       }
       ...

See also:

 Message_get_buffer.

bool Message_is_broadcast (

struct Message * ptr_message )

Determines if the message has no specific address.

Parameters:

ptr_message

 A pointer to the initialized Message object

Returns:

 TRUE if the message has no specific address
       #include <cybiko.h>
       #define MSG_TASK_REQUEST     MSG_USER + 1
       ...
       struct module_t  main_module;
       ...
       init_module( &main_module );
       ...
       struct Message* ptr_message = cWinApp_get_message( main_module.m_process,
                                                          0,
                                                          1,
                                                          MSG_TASK_REQUEST );
       if( Message_is_broadcast( ptr_message ) )
       {
         //  Declines task.
       }
       else
       {
         //  Accepts task.
       }
       ...

struct Message * Message_new (

size_t sizeof_message )

Returns a new Message from the system stores.

Parameters:

sizeof_message

 The size of the Message structure

Returns:

 A pointer to the Message object
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct Message* ptr_message = Message_new( sizeof( struct Message ) );
       ptr_message->msgid = MSG_TEST;
       //  Sends the message to the 'data_reciever' process which
       //  is on the same computer.
       Message_post( ptr_message, "data_reciever", get_own_id() );
       ...

bool Message_post ( | struct Message * ptr_message,
 | char * sz_process_name,
 | cyid_t cyid )

Posts a message to a specified target.

Parameters:

ptr_message
   |
 A pointer to the initialized Message object.

sz_process_name
   |
 The target process' name

cyid
   |
 The target computer's Cy ID

Returns:

 TRUE if a local Message was put into the Process' Queue
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct Message* ptr_message = Message_new( sizeof( struct Message ) );
       ptr_message->msgid = MSG_TEST;
       //  Sends the message to the 'data_reciever' process which
       //  is on the same computer.
       Message_post( ptr_message, "data_reciever", get_own_id() );
       ...

See also:

 Message_post_all.

void Message_post_all ( | struct Message * ptr_message,
 | short mask )

Posts a message to all Queues.

Parameters:

ptr_message
   |
 A pointer to the initialized Message object.

mask
   |
 One of the following: QF_NONE, QF_DEVICES, QF_FILES, QF_APPMASK, QF_ALL.

Returns:

 None
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct Message* ptr_message = Message_new( sizeof( struct Message ) );
       ptr_message->msgid = MSG_TEST;
       //  Sends the message to all. This message will receive all
       //  processes on the Cybiko computer.
       Message_post_all( ptr_message, QF_ALL );
       ...

See also:

 Message_post.

delivery_t Message_wait_delivery ( | struct Message * ptr_message,
 | struct Flag * ptr_flag )

Waits until Message delivery is completed or flag is set.

Parameters:

ptr_message
   |
 A pointer to the initialized Message object

ptr_flag
   |
 A pointer to the synchronizing object, or 0

Returns:

 Message delivery state
       #include <cybiko.h>
       #define MSG_TEST     MSG_USER + 1
       ...
       struct module_t main_module;
       struct Flag delivery_flag;
       char partner_name[9];
       cyid_t partner_id;
       ...
       init_module( &main_module );
       ...
       partner_id = select_game_partner( main_module.m_process,
                                         "Billiard",
                                         SGP_CYBIKO | SGP_HOT_SEAT,
                                         partner_name );
       if( partner_id )
       {
         ...
         struct Message* ptr_message = Message_new( sizeof( struct Message ) );
         ptr_message->msgid = MSG_TEST;
         //  Sends message to the "Billiard" application on the remote computer.
         Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
       }
       Flag_ctor(&delivery_flag, "MessageMutex", TRUE);
       if( Message_wait_delivery( ptr_message, &delivery_flag ) == DL_SUCCESS )
       {
         TRACE( "Message was delivered successfully" );
       }
       Flag_dtor(&delivery_flag, LEAVE_MEMORY);
       ...

Member Data Documentation

cyid_t cyid_from

Cy ID of the sender device.

cyid_t cyid_to

Cy ID of the target device.

bool deleted

TRUE if the Message has been deleted from the queue.

char * dst_name

The name of the target process.

short msgid

ID of the Message.

struct Message * next

Pointer to the next Message in the queue.

long param[2]

Additional parameters for the Message.


Selecting Remote Partners

Enumerations
enum {
SGP_NONE = 0x0,
SGP_HOT_SEAT = 0x4,
SGP_CYBIKO = 0x2,
SGP_CYBIKO_EASY = 0x10,
SGP_CYBIKO_HARD = 0x20,
SGP_SINGLE_GAME = 0x40,
SGP_CYLANDIA = 0x100,
SGP_DONT_INVITE = 0x8000
}
enum {
SGP_RES_HOT_SEAT = -3L,
SGP_RES_CYBIKO = -2L,
SGP_RES_CYBIKO_EASY = -5L,
SGP_RES_CYBIKO_HARD = -6L,
SGP_RES_SINGLE_GAME = -7L
}
enum invite_mode_t {
IM_DEFAULT = 0x1000000,
IM_GAME = 0x02000000,
IM_CHAT = 0x3000000,
IM_PHONEBOOK = 0x4000000
}

Functions
cyid_t | select_partner (struct Process *ptr_process, int style, char *sz_partner_name)
cyid_t | select_partner_Ex (struct Process *ptr_process, int style, char *sz_partner_name, char *sz_caption, cyid_t *exclude_cyids)
cyid_t | select_app_partner (struct Process *ptr_process, char *sz_text, int style, char *sz_partner_name, char *sz_caption, long invite_mode, cyid_t *exclude_cyids)
cyid_t | select_game_partner (struct Process *ptr_process, char *sz_game_name, long style, char *sz_partner_name)

Detailed Description

These structures allow the user to find a partner for a multiplayer game.

Enumeration Type Documentation

anonymous enum

"Select partner" dialog styles.

Enumeration values:
SGP_NONE | No additional strings.
SGP_HOT_SEAT | Allows user to select a game in hot seat mode on one CYBIKO computer.
SGP_CYBIKO | Allows the user to select the Cybiko computer as a game play partner.
SGP_CYBIKO_EASY | Allows the user to select the Cybiko computer as an Easy game play partner.
SGP_CYBIKO_HARD | Allows the user to select the Cybiko computer as a Hard game partner.
SGP_SINGLE_GAME | Allows the user to play the game without a partner.
SGP_CYLANDIA | Shows CYPETNAMEs instead of NICKNAMEs in the "select partner" dialog.
SGP_DONT_INVITE | Does not invite a partner; only selects nickname from list and retrieves the partner's Cy ID.

anonymous enum

Results of the "select partner" functions.

Enumeration values:
SGP_RES_HOT_SEAT | Game in hot seat mode on one CYBIKO computer.
SGP_RES_CYBIKO | Game with the CYBIKO computer as a partner.
SGP_RES_CYBIKO_EASY | Game with the CYBIKO computer as an Easy partner.
SGP_RES_CYBIKO_HARD | Game with the CYBIKO computer as a Hard partner.
SGP_RES_SINGLE_GAME | Game without a partner.

enum invite_mode_t

Modes of invitation.

Enumeration values:
IM_DEFAULT | Shows "Yes" and "No" buttons.
IM_GAME | Makes dialog text to look like "<NICKNAME> wants to play <GAME>. Play?" and shows "Yes" and "No" buttons
IM_CHAT | Shows "Chat" and "Cancel" buttons.
IM_PHONEBOOK | Makes dialog text to look like " wishes to send you a B-Card. Accept?" and shows "Yes" and "No" buttons

Function Documentation

cyid_t select_app_partner ( | struct Process * ptr_process,
 | char * sz_text,
 | int style,
 | char * sz_partner_name,
 | char * sz_caption,
 | long invite_mode,
 | cyid_t * exclude_cyids )

Invites a partner to launch a specified application.
If the user's partner accepts the invitation, the application will launch on his CYBIKO computer. ulong module_main (uint argc, char* argv[], bool start) of the invited application will have 2 parameters :

  • string with the partner's computer Cy ID
  • string with the partner's Cy Name
Parameters:
ptr_process | The pointer to the Process object that calls the function
sz_text | The invitation text or game name if the invite_mode is IM_GAME
style | The dialog style. This parameter can be any combination of the following values: SGP_NONE, SGP_HOT_SEAT, SGP_CYBIKO, SGP_CYBIKO_EASY, SGP_CYBIKO_HARD, SGP_SINGLE_GAME, SGP_CYLANDIA, SGP_DONT_INVITE
sz_partner_name | A pointer to the buffer in which the partner's Cy Name will be stored
sz_caption | The "select partner" dialog caption
invite_move | An invitation mode. This parameter can be one of the following values: IM_DEFAULT, IM_CHAT, IM_GAME, IM_PHONEBOOK
exclude_cyids | An array of computer's Cy IDs, whose Cy Names will be excluded from the "select partner" dialog
Returns:
If the function succeeds, the Cy ID of the partner's computer, or special ID ( SGP_RES_HOT_SEAT, SGP_RES_CYBIKO, SGP_RES_CYBIKO_EASY, SGP_RES_CYBIKO_HARD, SGP_RES_SINGLE_GAME ). If the function fails or player presses "Escape", the return value is 0
       #include <cybiko.h>
       ...
       ulong module_main(uint argc, char* argv[], bool start)
       {
         ...
         struct module_t main_module;
         char sz_partner_name[9];
         cyid_t partner_id;
         cyid_t exclude_list[2] = { 110, NULL };
         ...
         init_module( &main_module );
         ...
         if(argc != 1)       //  Application was invited.
         {
           partner_id = atoul(argv[1]);
           strcpy(sz_partner_name, argv[2]);
         }
         else               //  Application will invite another application.
         {
           //  Nickname of the computer with Cy ID 110 will be excluded from the
           //  list of available partners.
           partner_id = select_app_partner( main_module.m_process,
                                            "Enter private chat?",
                                            SGP_NONE,
                                            sz_partner_name,
                                            "Available Partners",
                                            IM_CHAT,
                                            exclude_list );
         }
         ...
         TRACE("Partner name: %s, partner computer id: %ld", sz_partner_name, partner_id );
         ...

cyid_t select_game_partner ( | struct Process * ptr_process,
 | char * sz_game_name,
 | long style,
 | char * sz_partner_name )

Select a partner for single or multi-player games.
If the user's partner accepts the invitation, the game will launch on his CYBIKO computer. ulong module_main (uint argc, char* argv[], bool start) of the invited application will have 2 parameters :

  • string with partner's computer's Cy ID
  • string with partner's Cy Name
Parameters:
ptr_process | The pointer to the Process object, that calls the function
sz_game_name | The name of the game the user wants his partner to play with him
style | The dialog style. This parameter can be any combination of the following values: SGP_NONE, SGP_HOT_SEAT, SGP_CYBIKO, SGP_CYBIKO_EASY, SGP_CYBIKO_HARD, SGP_SINGLE_GAME, SGP_CYLANDIA, SGP_DONT_INVITE
sz_partner_name | A pointer to the buffer in which the partner's Cy Name of your will be stored
Returns:
If the function succeeds, Cy ID of the partner's computer, or special ID ( SGP_RES_HOT_SEAT, SGP_RES_CYBIKO, SGP_RES_CYBIKO_EASY, SGP_RES_CYBIKO_HARD, SGP_RES_SINGLE_GAME ). If the function fails or the player presses "Escape", the return value is 0
       #include <cybiko.h>
       ...
       ulong module_main(uint argc, char* argv[], bool start)
       {
         ...
         struct module_t main_module;
         char sz_partner_name[9];
         cyid_t partner_id;
         ...
         init_module( &main_module );
         ...
         if(argc != 1)       //  Application was invited.
         {
           partner_id = atoul(argv[1]);
           strcpy(sz_partner_name, argv[2]);
         }
         else               //  Application will invite another application.
         {
           partner_id = select_game_partner( main_module.m_process,
                                             "Billiard",
                                             SGP_CYBIKO | SGP_HOT_SEAT,
                                             sz_partner_name );
         }
         ...
         TRACE("Partner name: %s, partner computer id: %ld", sz_partner_name, partner_id );
         ...

cyid_t select_partner ( | struct Process * ptr_process,
 | int style,
 | char * sz_partner_name )

Selects a partner.

Parameters:
ptr_process | The pointer to the Process object, that calls the function
style | The dialog style. This parameter can be any combination of the following values: SGP_NONE, SGP_HOT_SEAT, SGP_CYBIKO, SGP_CYBIKO_EASY, SGP_CYBIKO_HARD, SGP_SINGLE_GAME, SGP_CYLANDIA, SGP_DONT_INVITE
sz_partner_name | A pointer to the buffer in which the partner's Cy Name will be stored
Returns:
If the function succeeds, ID of the partner's computer, or special ID ( SGP_RES_HOT_SEAT, SGP_RES_CYBIKO, SGP_RES_CYBIKO_EASY, SGP_RES_CYBIKO_HARD, SGP_RES_SINGLE_GAME ). If the function fails or player presses "Escape", the return value is 0
       #include <cybiko.h>
       ...
       struct module_t main_module;
       char sz_partner_name[9];
       cyid_t partner_id;
       ...
       init_module( &main_module );
       ...
       partner_id = select_partner( main_module.m_process,
                                    SGP_SINGLE_GAME,
                                    sz_partner_name );
       if( ( partner_id )
          && ( partner_id != SGP_RES_SINGLE_GAME ) )
       {
         ...
         TRACE("Partner name: %s, partner computer id: %ld", sz_partner_name, partner_id );
         ...
       }
       ...
See also:
select_partner_Ex.

cyid_t select_partner_Ex ( | struct Process * ptr_process,
 | int style,
 | char * sz_partner_name,
 | char * sz_caption,
 | cyid_t * exclude_cyids )

Extended version of the select_partner function.

Parameters:
ptr_process | The pointer to the Process object, that calls the function
sz_partner_name | A pointer to the buffer in which the partner's Cy Name will be stored
style | The dialog style. This parameter can be any combination of the following values: SGP_NONE, SGP_HOT_SEAT, SGP_CYBIKO, SGP_CYBIKO_EASY, SGP_CYBIKO_HARD, SGP_SINGLE_GAME, SGP_CYLANDIA, SGP_DONT_INVITE
sz_caption | The "select partner" dialog caption
exclude_cyids | NULL-terminated array of the Cybiko computer's IDs, whose Cy Names will be excluded from the "select partner" dialog
Returns:
If the function succeeds, Cy ID of the partner computer or special ID ( SGP_RES_HOT_SEAT, SGP_RES_CYBIKO, SGP_RES_CYBIKO_EASY, SGP_RES_CYBIKO_HARD, SGP_RES_SINGLE_GAME ). If the function fails or player presses "Escape", the return value is 0
       #include <cybiko.h>
       ...
       struct module_t main_module;
       char partner_name[9];
       cyid_t sz_partner_id;
       cyid_t exclude_list[2] = { 110, NULL };
       ...
       init_module( &main_module );
       ...
       //  Nickname of the computer with Cy ID 110 will be excluded from the
       //  list of available partners.
       partner_id = select_partner_Ex( main_module.m_process,
                                       SGP_SINGLE_GAME,
                                       sz_partner_name,
                                       "Available Partners",
                                       exclude_list );
       if( ( partner_id ) && ( partner_id != SGP_RES_SINGLE_GAME ) )
       {
         ...
         TRACE("Partner name: %s, partner computer id: %ld", sz_partner_name, partner_id );
         ...
       }
       ...
See also:
select_partner.


Finder-related

Defines
#define | NICKNAMESIZE 8
#define | NAMESIZE 15
#define | CYPETNAMESIZE 7
#define | NOT_FOUND 0xFF
#define | STR_ICQ_MAX_LENGTH 10

Variables
char | own_icq []
char | own_icq_visible

Compounds
struct | cyfolk_t | Describes a person on the Finder's list
struct | Finder | Finder is a resident program; that is, it is always in memory. It's main purpose is to gather information about the Cy-environment
struct | folk_t | Describes the " You&me/About Me " and " You&me/About You " information
struct | info_t | Describes the " You&me/Business Card " information
struct | nfolk_t | Additional information about a person in Finder's list

Detailed Description

With these structures, you can gather information about the Cy-environment (that is, the other people and Cybiko computers in the vicinity). Finder is probably the most important of these structures.

Define Documentation

#define CYPETNAMESIZE 7

Maximum length of the Cypet name.

#define NAMESIZE 15

Maximum length of the name.

#define NICKNAMESIZE 8

Maximum length of the nickname.

#define NOT_FOUND 0xFF

Person with the specified parameter not found.

#define STR_ICQ_MAX_LENGTH 10

Maximum length of the ICQ number.

Variable Documentation

char own_icq[]

ICQ number of the device owner.

       #include <cybiko.h>
       ...
       TRACE("Your ICQ number is %s", own_icq);
       if(own_icq_visible)
       {
         TRACE("Your ICQ number is visible to people around.");
       }
       else
       {
         TRACE("Your ICQ number is not visible to people around.");
       }
       ...

char own_icq_visible

ICQ number visibility flag.

       #include <cybiko.h>
       ...
       TRACE("Your ICQ number is %s", own_icq);
       if(own_icq_visible)
       {
         TRACE("Your ICQ number is visible to people around.");
       }
       else
       {
         TRACE("Your ICQ number is not visible to people around.");
       }
       ...


cyfolk_t Struct Reference

Collaboration diagram for cyfolk_t:

Public Attributes
long | cf_id
struct nfolk_t | cf_fk
char | cf_my_match
char | cf_match
char | cf_name_ind

Detailed Description

Describes a person in the Finder's list.

See also:
Finder-related

Member Data Documentation

struct nfolk_t cf_fk

Additional information about the person listed.

long cf_id

Cy ID of the user's Cybiko device.

char cf_match

Mean match coefficient of person and device owner.

char cf_my_match

The mean match coefficient of the listed person - and the device's owner.

char cf_name_ind

Number of people with the same nickname in the Finder's list.


Finder Struct Reference

Inheritance diagram for Finder

Collaboration diagram for Finder:

Public Methods
char | Finder_find_active (struct Finder *ptr_finder, cyid_t cyber_id)
char | Finder_find_unknown (struct Finder *ptr_finder, cyid_t cyber_id)
char | Finder_find_disap (struct Finder *ptr_finder, cyid_t cyber_id)
char | Finder_age (struct Finder *ptr_finder, char day, char month, char year)
char* | Finder_create_name (struct Finder *ptr_finder, char *sz_visible_name, struct cyfolk_t *person_info)
int | Finder_get_best_ids (struct Finder *ptr_finder, cyid_t *ptr_cyid_buff, int number)

Public Attributes
struct Mutex | finder_mutex
char | howmany_around
char | howboys_around
char | howmany_unknown
char | howmany_disap
struct folk_t | mf
struct info_t | mi
struct cyfolk_t* | cf
struct Finder | finder

Detailed Description

Finder is a resident program, that is, it is always in memory. It's main purpose is to gather information about the Cy-environment. If another Cybiko appears within the "field of vision" (if we get any message from it), the Finder begins the acquaintance procedure. It sends the identification information "You&Me/About me" and "You&Me/About you", and requests the same information from the unknown Cybiko. Then the Finder calculates the match coefficients (hearts). If our common coefficient is equal to 3 hearts, the Finder creates a dialog, informing the user of our Cy-friend's appearance. The Finder also grants information about other users in the vicinity to other programs, including People and Chat.

The finder can also tell you other information. The total number of active people is stored in the field finder.howmany_around. The total number of unknown users is stored in howmany_unknown. The "cf" field holds an array of records, each describing some aspects of other Cybikos: Cyid, nickname, gender, age etc.

See also:
Finder-related

Member Function Documentation

char Finder_age ( | struct Finder * ptr_finder,
 | char day,
 | char month,
 | char year )

Calculates the user's age from his/her last birthday.

Parameters:
ptr_finder | The Finder object. MUST BE &finder!
day | Day of birth
month | Month of birth
year | Year of birth
Returns:
Current age
       #include <cybiko.h>
       ...
       TRACE("Your age is: %d", Finder_age(&finder,
                                           finder.mi.i_bday,
                                           finder.mi.i_bmonth,
                                           finder.mi.i_byear));
       ...

char * Finder_create_name ( | struct Finder * ptr_finder,
 | char * sz_visible_name,
 | struct cyfolk_t * person_info )

Alters a real name to create a visible name form.
For example, if two "visible" Cybikos have the same nickname ("Cy", for instance), the Finder can alter one of their names so the user can tell them apart (for example, showing one as "Cy" and the other as "Cy1").

Parameters:
ptr_finder | The Finder object. MUST BE &finder!
sz_visible_name | The buffer where the visible (altered) name will be placed
person_info | Person information about the other user whose Cybiko name is being altered
Returns:
The visible name.
       #include <cybiko.h>
       ...
       int index;
       int finder_list_index;
       int friend_candidates_number;
       cyid_t friend_candidates[10];
       char sz_friend_candidate_name[16];
       ...
       friend_candidates_number = Finder_get_best_ids(&finder,
                                                      friend_candidates,
                                                      10);
       TRACE("Friend candidates:");
       for(index = 0; index < friend_candidates_number; index ++)
       {
         finder_list_index = Finder_find_active(&finder,
                                                friend_candidates[index]);
         if(finder_list_index != NOT_FOUND)
         {
           Finder_create_name(&finder,
                              sz_friend_candidate_name,
                              &finder.cf[finder_list_index]);
           TRACE("%s", sz_friend_candidate_name);
         }
       }
       ...

char Finder_find_active ( | struct Finder * ptr_finder,
 | cyid_t cyber_id )

Finds the active person's position in finder.cf array.

Parameters:
ptr_finder | The Finder object. MUST BE &finder!
cyber_id | Cy ID of the other person's device
Returns:
Position in the finder.cf, or NOT_FOUND, if the other user is not active
       #include <cybiko.h>
       ...
       int index;
       int finder_list_index;
       int friend_candidates_number;
       cyid_t friend_candidates[10];
       char sz_friend_candidate_name[16];
       ...
       friend_candidates_number = Finder_get_best_ids(&finder,
                                                      friend_candidates,
                                                      10);
       TRACE("Friend candidates:");
       for(index = 0; index < friend_candidates_number; index ++)
       {
         finder_list_index = Finder_find_active(&finder,
                                                friend_candidates[index]);
         if(finder_list_index != NOT_FOUND)
         {
           Finder_create_name(&finder,
                              sz_friend_candidate_name,
                              &finder.cf[finder_list_index]);
           TRACE("%s", sz_friend_candidate_name);
         }
       }
       ...
See also:
NOT_FOUND.

char Finder_find_disap ( | struct Finder * ptr_finder,
 | cyid_t cyber_id )

Finds the position in the finder.cf array of the person who temporarily disappeared from the finder's environment.

Parameters:
ptr_finder | The Finder object. MUST BE &finder!
cyber_id | The Cy ID of the other person's device
Returns:
Position in finder.cf or NOT_FOUND, if the other user is not founded
       #include <cybiko.h>
       ...
       char* get_nickname_by_id( char* sz_nickname, cyid_t id )
       {
         char index;
         Mutex_lock( &finder.finder_mutex, 0 );
         if( ( index = Finder_find_active( &finder, id ) ) != NOT_FOUND )
         {
           //  Person is in the list of active people.
           Finder_create_name( &finder, sz_nickname, &finder.cf[index] );
         }
         else if( ( index = Finder_find_unknown( &finder, id ) ) != NOT_FOUND )
         {
           //  Person is in the list of unknown people.
           strcpy( sz_nickname, "unknown" );
         }
         else if( ( index = Finder_find_disap( &finder, id ) ) != NOT_FOUND)
         {
           //  Finds people in the list of people who temporarily
           //  disappeared from the finder's environment.
           Finder_create_name( &finder, sz_nickname, &finder.cf[index] );
         }
         else
         {
           //  We have never met the device with the specified Cy ID.
           strcpy( sz_nickname, "no info" );
         }
         Mutex_unlock( &finder.finder_mutex );
         return sz_nickname;
       }
       ...
See also:
NOT_FOUND.

char Finder_find_unknown ( | struct Finder * ptr_finder,
 | cyid_t cyber_id )

Finds the position of the unknown person in the finder.cf array.

Parameters:
ptr_finder | The Finder object. MUST BE &finder!
cyber_id | The Cy ID of the other person's device
Returns:
Position in finder.cf or NOT_FOUND, if the other user is not found
       #include <cybiko.h>
       ...
       char* get_nickname_by_id( char* sz_nickname, cyid_t id )
       {
         char index;
         Mutex_lock( &finder.finder_mutex, 0 );
         if( ( index = Finder_find_active( &finder, id ) ) != NOT_FOUND )
         {
           //  Person is in the list of active people.
           Finder_create_name( &finder, sz_nickname, &finder.cf[index] );
         }
         else if( ( index = Finder_find_unknown( &finder, id ) ) != NOT_FOUND )
         {
           //  Person is in the list of unknown people.
           strcpy( sz_nickname, "unknown" );
         }
         else if( ( index = Finder_find_disap( &finder, id ) ) != NOT_FOUND)
         {
           //  Finds people in the list of people who temporarily
           //  disappeared from the finder's environment.
           Finder_create_name( &finder, sz_nickname, &finder.cf[index] );
         }
         else
         {
           //  We have never met the device with the specified Cy ID.
           strcpy( sz_nickname, "no info" );
         }
         Mutex_unlock( &finder.finder_mutex );
         return sz_nickname;
       }
       ...
See also:
NOT_FOUND.

int Finder_get_best_ids ( | struct Finder * ptr_finder,
 | cyid_t * ptr_cyid_buff,
 | int number )

Gets the Cy IDs of the devices with the best match coefficient.

Parameters:
ptr_finde | The Finder object. MUST BE &finder!
ptr_cyid_buff | The buffer for Cy IDs
number | The desired number of Cy IDs.
Returns:
Number of Cy IDs stored in the buffer.
       #include <cybiko.h>
       ...
       int index;
       int finder_list_index;
       int friend_candidates_number;
       cyid_t friend_candidates[10];
       char sz_friend_candidate_name[16];
       ...
       friend_candidates_number = Finder_get_best_ids(&finder,
                                                      friend_candidates,
                                                      10);
       TRACE("Friend candidates:");
       for(index = 0; index < friend_candidates_number; index ++)
       {
         finder_list_index = Finder_find_active(&finder,
                                                friend_candidates[index]);
         if(finder_list_index != NOT_FOUND)
         {
           Finder_create_name(&finder,
                              sz_friend_candidate_name,
                              &finder.cf[finder_list_index]);
           TRACE("%s", sz_friend_candidate_name);
         }
       }
       ...

Member Data Documentation

struct cyfolk_t * cf

Array of records describing the people in the vicinity.

struct Finder finder

Global Finder object.
Must be used as the first parameter of all Finder_ functions.

       #include <cybiko.h>
       ...
       struct Time current_time;
       ...
       Time_get_RTC(&current_time);
       if((current_time.month == finder.mi.i_bmonth)
          &&(current_time.day == finder.mi.i_bday))
       {
         TRACE("Happy birthday!");
       }
       ...

struct Mutex finder_mutex

Mutually exclusive access synchronization object.

char howboys_around

Number of boys around.

char howmany_around

Number of people around.

char howmany_disap

Number of people around who temporarily disappeared from the finder's environment.

char howmany_unknown

Number of people around whose nicknames are "unknown".

struct folk_t mf

The user's own profile.

struct info_t mi

The user's own business card.


folk_t Struct Reference

Public Attributes
char | f_nick [NICKNAMESIZE+1]
char | f_gender
char | f_age_visible
char | f_age
char | f_height
char | f_weight
char | f_purpose
char | f_purpose_visible
char | f_height_visible
char | f_weight_visible
char | f_hobby1_visible
char | f_hobby2_visible
char | f_hobby3_visible
char | f_hobby1
char | f_hobby2
char | f_hobby3
char | f_secret1 [NICKNAMESIZE+1]
char | f_secret2 [NICKNAMESIZE+1]
char | f_secret3 [NICKNAMESIZE+1]
char | f_seek_gender
char | f_seek_gender_degree
char | f_min_age
char | f_max_age
char | f_seek_age_degree
char | f_min_height
char | f_max_height
char | f_seek_height_degree
char | f_min_weight
char | f_max_weight
char | f_seek_weight_degree
char | f_seek_purpose
char | f_seek_purpose_degree
char | f_seek_hobby1
char | f_seek_hobby2
char | f_seek_hobby3
char | f_seek_hobby1_degree
char | f_seek_hobby2_degree
char | f_seek_hobby3_degree
char | f_seek_secret1_degree
char | f_seek_secret2_degree
char | f_seek_secret3_degree
char | f_seek_secret1 [NICKNAMESIZE+1]
char | f_seek_secret2 [NICKNAMESIZE+1]
char | f_seek_secret3 [NICKNAMESIZE+1]

Detailed Description

Describes the " You&me/About Me " " You&me/About You " information.

See also:
Finder-related

Member Data Documentation

char f_age

Age.

char f_age_visible

Age visibility flag.

char f_gender

Gender.
0:male, 1:female.

char f_height

Height.

char f_height_visible

Height visibility flag.

char f_hobby1

Hobby 1.
1:no, 2:Cybiko, 3:Soccer, 4:Chess, 5:Rollerblading, 6:Skateboarding, 7:Skydiving, 8:BMX, 9:Music, 10:Gaming, 11:Dance, 12:Internet, 13:Computer, 14:Sports, 15:Arts, 16:Science/Tech, 17:Travel,18:Mountain Biking, 19:Books, 20:Movies, 21:Skiing, 22:Girls, 23:Boys, 24:does not matter

char f_hobby1_visible

Hobby 1 visibility flag.

char f_hobby2

Hobby 2.
1:no, 2:Cybiko, 3:Soccer, 4:Chess, 5:Rollerblading, 6:Skateboarding, 7:Skydiving, 8:BMX, 9:Music, 10:Gaming, 11:Dance, 12:Internet, 13:Computer, 14:Sports, 15:Arts, 16:Science/Tech, 17:Travel,18:Mountain Biking, 19:Books, 20:Movies, 21:Skiing, 22:Girls, 23:Boys, 24:does not matter

char f_hobby2_visible

Hobby 2 visibility flag.

char f_hobby3

Hobby 3.
1:no, 2:Cybiko, 3:Soccer, 4:Chess, 5:Rollerblading, 6:Skateboarding, 7:Skydiving, 8:BMX, 9:Music, 10:Gaming, 11:Dance, 12:Internet, 13:Computer, 14:Sports, 15:Arts, 16:Science/Tech, 17:Travel,18:Mountain Biking, 19:Books, 20:Movies, 21:Skiing, 22:Girls, 23:Boys, 24:does not matter

char f_hobby3_visible

Hobby 3 visibility flag.

char f_max_age

Maximal age of friend to seek.

char f_max_height

Maximal height of friend to seek.

char f_max_weight

Maximal weight of friend to seek.

char f_min_age

Minimal age of friend to seek.

char f_min_height

Minimal height of friend to seek.

char f_min_weight

Minimal weight of friend to seek.

char f_nick[NICKNAMESIZE+1]

Nickname.

char f_purpose

Purpose to find friend.
0:Business, 1:Romance, 2:Sports, 3:Chat, 4:Other

char f_purpose_visible

Purpose visibility flag.

char f_secret1[NICKNAMESIZE+1]

secret field 1.

char f_secret2[NICKNAMESIZE+1]

secret field 2.

char f_secret3[NICKNAMESIZE+1]

secret field 3.

char f_seek_age_degree

Importance of age of friend to seek(0 - 5).

char f_seek_gender

Gender of friend to seek.
0:male, 1:female, 2:does not matter.

char f_seek_gender_degree

Importance of gender of friend to seek(0 - 5).

char f_seek_height_degree

Importance of height of friend to seek(0 - 5).

char f_seek_hobby1

Hobby 1 of friend to seek.
1:no, 2:Cybiko, 3:Soccer, 4:Chess, 5:Rollerblading, 6:Skateboarding, 7:Skydiving, 8:BMX, 9:Music, 10:Gaming, 11:Dance, 12:Internet, 13:Computer, 14:Sports, 15:Arts, 16:Science/Tech, 17:Travel,18:Mountain Biking, 19:Books, 20:Movies, 21:Skiing, 22:Girls, 23:Boys, 24:does not matter

char f_seek_hobby1_degree

Importance of hobby 1 of friend to seek(0 - 5).

char f_seek_hobby2

Hobby 2 of friend to seek.
1:no, 2:Cybiko, 3:Soccer, 4:Chess, 5:Rollerblading, 6:Skateboarding, 7:Skydiving, 8:BMX, 9:Music, 10:Gaming, 11:Dance, 12:Internet, 13:Computer, 14:Sports, 15:Arts, 16:Science/Tech, 17:Travel,18:Mountain Biking, 19:Books, 20:Movies, 21:Skiing, 22:Girls, 23:Boys, 24:does not matter

char f_seek_hobby2_degree

Importance of hobby 2 of friend to seek(0 - 5).

char f_seek_hobby3

Hobby 3 of friend to seek.
1:no, 2:Cybiko, 3:Soccer, 4:Chess, 5:Rollerblading, 6:Skateboarding, 7:Skydiving, 8:BMX, 9:Music, 10:Gaming, 11:Dance, 12:Internet, 13:Computer, 14:Sports, 15:Arts, 16:Science/Tech, 17:Travel,18:Mountain Biking, 19:Books, 20:Movies, 21:Skiing, 22:Girls, 23:Boys, 24:does not matter

char f_seek_hobby3_degree

Importance of hobby 3 of friend to seek(0 - 5).

char f_seek_purpose

Purpose to find friend.
0:Business, 1:Romance, 2:Sports, 3:Chat, 4:Other

char f_seek_purpose_degree

Importance of purpose of friend to seek(0 - 5).

char f_seek_secret1[NICKNAMESIZE+1]

Secret field 1 of friend to seek.

char f_seek_secret1_degree

Importance of secret field 1 of friend to seek(0 - 5).

char f_seek_secret2[NICKNAMESIZE+1]

Secret field 2 of friend to seek.

char f_seek_secret2_degree

Importance of secret field 2 of friend to seek(0 - 5).

char f_seek_secret3[NICKNAMESIZE+1]

Secret field 3 of friend to seek.

char f_seek_secret3_degree

Importance of secret field 3 of friend to seek(0 - 5).

char f_seek_weight_degree

Importance of weight of friend to seek(0 - 5).

char f_weight

Weight.

char f_weight_visible

Weight visibility flag.


info_t Struct Reference

Public Attributes
char | i_first_name [NAMESIZE+1]
char | i_last_name [NAMESIZE+1]
char | i_phone [21]
char | i_mail [31]
char | i_addr [31]
char | i_other [41]
char | i_bday
char | i_bmonth
char | i_byear
char | i_first_name_visible
char | i_last_name_visible
char | i_phone_visible
char | i_mail_visible
char | i_addr_visible
char | i_other_visible

Detailed Description

Describes the "You&me/Business Card" information.

See also:
Finder-related

Member Data Documentation

char i_addr[31]

Address.

char i_addr_visible

Address visibility flag.

char i_bday

Birthday, day of the month.

char i_bmonth

Birthday, month.

char i_byear

Birthday, year.

char i_first_name[NAMESIZE+1]

Real first name.

char i_first_name_visible

First name visibility flag.

char i_last_name[NAMESIZE+1]

Real last name.

char i_last_name_visible

Last name visibility flag.

char i_mail[31]

E-mail address.

char i_mail_visible

E-mail address visibility flag.

char i_other[41]

Other contacts.

char i_other_visible

Other contacts visibility flag.

char i_phone[21]

Phone number.

char i_phone_visible

Phone number visibility flag.


nfolk_t Struct Reference

Public Attributes
char | f_nick [NICKNAMESIZE+1]
char | f_gender
char | f_age_visible
char | f_age

Detailed Description

Additional information about a person in Finder's list.

See also:
Finder-related

Member Data Documentation

char f_age

Age.

char f_age_visible

Age visibility flag.

char f_gender

Gender.

char f_nick[NICKNAMESIZE+1]

Nickname.


Low Level

Defines
#define | RF_GROUP_DEFAULT 0
#define | RF_GROUP_CHAT 1
#define | RF_GROUP_CYLAND 2
#define | RF_GROUP_LABYRINTH 3
#define | RF_GROUP_SERVER 4
#define | RF_GROUP_FILES 5
#define | RF_GROUP_GAMES 6
#define | RF_GROUP_APPS 7
#define | RF_GROUP_OTHER 8
#define | RF_GROUP_SYSTEM 9

Functions
bool | get_communications (void)
void | set_communications (bool enable)
char | get_appchannel (void)
char | get_appchannel_of (cyid_t device_id)
void | set_appchannel (char rf_channel)
char | set_best_appchannel (char group_id)
char | get_groupchannel (char group_id, char channel)
char | set_groupchannel (char group_id, char channel)
char | get_group_size (char group)
int | get_people_on_channel (char channel)
cyid_t | get_people_around (cyid_t prev_device)
void | update_people_around (clock_t timeout)
bool | is_rf_paused (void)
void | rf_pause (void)
void | rf_resume (void)
clock_t | last_rf_clock (void)
time_t | last_rf_time (void)
bool | set_critical_mode (bool set)
bool | get_critical_mode (void)

Detailed Description

Some low level communication functions. Don't use these functions if you don't know exactly what are you doing.

Define Documentation

#define RF_GROUP_APPS 7

Applications channel group.

#define RF_GROUP_CHAT 1

Chat channel group.

#define RF_GROUP_CYLAND 2

CyLandia channel group.

#define RF_GROUP_DEFAULT 0

Default group for unknown applications.

#define RF_GROUP_FILES 5

Files channel group.

#define RF_GROUP_GAMES 6

Games channel group.

#define RF_GROUP_LABYRINTH 3

Labyrinth channel group.

#define RF_GROUP_OTHER 8

Reserved channel group.

#define RF_GROUP_SERVER 4

Server channel group.

#define RF_GROUP_SYSTEM 9

System channel group (for debugging purposes).

Function Documentation

char get_appchannel ( void )

Returns the current application's channel.

Returns:
the current application channel.
       #include <cybiko.h>
       #define PRIVATE_CHAT_CHANNEL    0x1
       ...
       char old_channel;
       ...
       //  Sets new application channel.
       old_channel = get_appchannel();
       set_appchannel( get_groupchannel( RF_GROUP_CHAT,
                                         PRIVATE_CHAT_CHANNEL ) );
       ...
       //  Restores application channel.
       set_appchannel( old_channel );
       ...
See also:
set_appchannel.

char get_appchannel_of ( cyid_t device_id )

Returns the current application channel of the specified device.

Parameters:
device_id the ID of the device, to determine its RF channel.
Returns:
current application channel of the specified device.
       #include<cybiko.h>
       ...
       char old_channel;
       cyid_t partner_id;
       ...
       //  Obtains partner_id.
       ...
       //  Sets application channel equal to your partner channel.
       old_channel = get_appchannel();
       set_appchannel( get_appchannel_of( partner_id ) );
       ...
       //  Restores application channel.
       set_appchannel( old_channel );
       ...
See also:
set_appchannel.

bool get_communications ( void )

Returns the communications state.

Returns:
TRUE if communications are enabled.
       #include <cybiko.h>
       ...
       if ( !get_communications() )
             set_communications( TRUE );
       ...
See also:
set_communications.

bool get_critical_mode ( void )

Returns the critical mode state.

Returns:
the critical mode state.
       #include <cybiko.h>
       ...
       if( ! get_critical_mode() )
       {
         set_critical_mode( TRUE );
       }
       ...

char get_group_size ( char group )

Returns the number of channels in a specified group.

Parameters:
group ID of the group.
Returns:
the number of channels in the group.
       #include <cybiko.h>
       ...
       char max_chat_channel;
       chat current_channel;
       int people_in_chat = 0;
       ...
       //  Counts all people on chat channels.
       max_chat_channel = get_group_size( RF_GROUP_CHAT );
       for( current_channel = 0; current_channel < max_chat_channel; current_channel ++ )
       {
         people_in_chat += get_people_on_channel( get_groupchannel( RF_GROUP_CHAT,
                                                                    current_channel ) );
       }
       ...

char get_groupchannel ( | char group_id,
 | char channel )

Returns the application channel, by channel group index.

Parameters:
group_id | ID of the group to which the application belongs.
channel | index of the application in the group.
Returns:
the application channel, by channel group index.
       #include <cybiko.h>
       #define PRIVATE_CHAT_CHANNEL    0x1
       ...
       char old_channel;
       ...
       //  Sets new application channel.
       old_channel = get_appchannel();
       set_appchannel( get_groupchannel( RF_GROUP_CHAT,
                                         PRIVATE_CHAT_CHANNEL ) );
       ...
       //  Restores application channel.
       set_appchannel( old_channel );
       ...
See also:
set_groupchannel.

cyid_t get_people_around ( cyid_t prev_device )

Returns the CyID of the next device after prev_device (the CyIDs of people in the vicinity).
To retrieve the first device in the list, set prev_device to zero.

Parameters:
prev_device CyID of the device in the previous CyID list of people in the vicinity.
Returns:
the CyID of a device.
       #include <cybiko.h>
       ...
       char sz_str_ID[10];
       cyid_t current_device_id = 0;
       ...
       TRACE( "Devices around:" );
       while( current_device_id = get_people_around( current_device_id ) )
       {
         cyid2str( sz_str_ID, current_device_id );
         TRACE( "%s", sz_str_ID );
       }
       ...

int get_people_on_channel ( char channel )

Returns the device count on the channel.

Parameters:
channel the index of the RF channel.
Returns:
the device count on the channel.
       #include <cybiko.h>
       ...
       char max_chat_channel;
       char current_channel;
       int people_in_chat = 0;
       ...
       //  Counts all people on chat channels.
       max_chat_channel = get_group_size( RF_GROUP_CHAT );
       for( current_channel = 0; current_channel < max_chat_channel; current_channel ++ )
       {
         people_in_chat += get_people_on_channel( get_groupchannel( RF_GROUP_CHAT,
                                                                    current_channel ) );
       }
       ...

bool is_rf_paused ( void )

Returns TRUE if RF communications are paused.

Returns:
TRUE if RF communications are paused.
       #include <cybiko.h>
       ...
       bool rf_paused;
       ...
       //  Disables communications.
       rf_paused = is_rf_paused();
       rf_pause();
       ...
       //  Restores communications.
       if( ! rf_paused )
       {
         rf_resume();
       }
       ...

clock_t last_rf_clock ( void )

Returns the clock_t value of the last sent or received frame except sent pings (last RF activity clock).

Returns:
the clock_t value of the last sent or received frame.
       #include <cybiko.h>
       ...
       int value;
       ...
       //  Initializes a pseudorandom sequence.
       srand( last_rf_clock() );
       ...
       value = random( 10 );
       ...

time_t last_rf_time ( void )

Returns the time the last frame was sent or received, except sent pings.

Returns:
the time the last frame was sent or received.
       #include <cybiko.h>
       ...
       struct Time last_message_time;
       ...
       Time_decode( &last_message_time, last_rf_time() );
       TRACE("Last message was sent or received at hour: %d, minutes: %d, seconds: %d",
             last_message_time.hour,
             last_message_time.minute,
             last_message_time.second );
       ...

void rf_pause ( void )

Pauses RF communications.
Another way to stop RF.

Returns:
None
       #include <cybiko.h>
       ...
       bool rf_paused;
       ...
       //  Disables communications.
       rf_paused = is_rf_paused();
       rf_pause();
       ...
       //  Restores communications.
       if( ! rf_paused )
       {
         rf_resume();
       }
       ...
See also:
rf_resume.

void rf_resume ( void )

Resumes RF communications after a pause.

Returns:
None
       #include <cybiko.h>
       ...
       bool rf_paused;
       ...
       //  Disables communications.
       rf_paused = is_rf_paused();
       rf_pause();
       ...
       //  Restores communications.
       if( ! rf_paused )
       {
         rf_resume();
       }
       ...
See also:
rf_pause.

void set_appchannel ( char rf_channel )

Sets current application channel.
The channel #0 is the Base channel.

Parameters:
rf_channel RF channel to set.
Returns:
None.
       #include <cybiko.h>
       #define PRIVATE_CHAT_CHANNEL    0x1
       ...
       char old_channel;
       ...
       //  Sets new application channel.
       old_channel = get_appchannel();
       set_appchannel( get_groupchannel( RF_GROUP_CHAT,
                                         PRIVATE_CHAT_CHANNEL ) );
       ...
       //  Restores application channel.
       set_appchannel( old_channel );
       ...
See also:
get_appchannel_of.

char set_best_appchannel ( char group_id )

Selects the application channel with the last traffic.

Parameters:
group_id ID of the group to which the application belongs.
Returns:
ID of the channel with the last traffic.
       #include <cybiko.h>
       ...
       char old_channel;
       ...
       // Sets application channel with the least traffic.
       old_channel = get_appchannel();
       set_best_appchannel( RF_GROUP_CHAT );
       ...
       //  Restores application channel.
       set_appchannel( old_channel );
       ...

void set_communications ( bool enable )

Enables or disables communications through RF.
Disabling RF communications turns off all communications devices (e.g. AVR, PLL and RF2915), so power consumption is decreased. Also, it disables periodically sending pings.

Parameters:
enable specifies whether communications should be enabled. A TRUE value enables communications; a FALSE value disables them.
Returns:
None.
       #include <cybiko.h>
       ...
       if( !get_communications() )
            set_communications( TRUE );
       ...
See also:
get_communications.

bool set_critical_mode ( bool set )

Sets a special critical mode to disable network or internal task interrupts, such as invite.

Parameters:
set if TRUE, enables critical mode; any other answer disables it
Returns:
previous state.
       #include <cybiko.h>
       ...
       if( ! get_critical_mode() )
       {
         set_critical_mode( TRUE );
       }
       ...

char set_groupchannel ( | char group_id,
 | char channel )

Selects the application channel by channel group index.

Parameters:
group_id | ID of the group to which the application belongs.
channel | index of the application in the group.
Returns:
returns the application channel.
       #include <cybiko.h>
       #define PRIVATE_CHAT_CHANNEL    0x1
       ...
       char old_channel;
       ...
       //  Sets new application channel.
       old_channel = get_appchannel();
       set_groupchannel( RF_GROUP_CHAT, PRIVATE_CHAT_CHANNEL );
       ...
       //  Restores application channel.
       set_appchannel( old_channel );
       ...
See also:
get_groupchannel.

void update_people_around ( clock_t timeout )

Selects the base channel, waits the timeout, and resets the work channel.

Parameters:
timeout the amount of time to wait.
Returns:
None.
       #include <cybiko.h>
       #define PRIVATE_CHAT_CHANNEL    0x1
       ...
       char old_channel;
       ...
       //  Sets new application channel.
       old_channel = get_appchannel();
       set_groupchannel( RF_GROUP_CHAT, PRIVATE_CHAT_CHANNEL );
       ...
       update_people_around( 250 );
       //  Retrives people arround.
       ...
       //  Restores application channel.
       set_appchannel( old_channel );
       ...


Drawing Primitives and Screen Manipulation

Defines
#define | SCREEN_WIDTH 160
#define | SCREEN_HEIGHT 100
#define | CLR_WHITE 0
#define | CLR_LTGRAY 85
#define | CLR_DKGRAY 171
#define | CLR_BLACK 255
#define | DM_PUT 0
#define | DM_OR 1
#define | DM_XOR 2
#define | ARROW_UP 0x01
#define | ARROW_DOWN 0x02

Typedefs
typedef int | color_t
typedef int | drawmode_t

Enumerations
enum {
RR_NONE = 0,
RR_ARROWUP = ARROW_UP,
RR_ARROWDOWN = ARROW_DOWN,
RR_ROUND = 4,
RR_ERASE = 8
}

Functions
void | draw_roundrect (struct Graphics *ptr_graphics, struct rect_t *ptr_rectangle, int style, char *sz_caption)
void | draw_bar (int x, int y, int width, int height, color_t color, bool xor)
void | rect (int x, int y, int width, int height, color_t color)
bool | in_rect (int x, int y, struct rect_t *ptr_rectangle)

Compounds
struct | DisplayGraphics | This structure is designited to execute any draw operation on the cybiko display. This structure is designited to execute any draw operation on the Cybiko computer's display. If you want to make draw operations on a bitmap object, it's best to use the Graphics structure. The Cybiko computer features two displays; one of them virtual. We refer to these displays as 'graphics pages.' The draw operations are performed on the virtual graphics page, and then shown as the Cybiko screen's graphics page
struct | Graphics | This structure allows draw operations to be applied to Bitmap objects
struct | rect_t | A rectangle
struct | TGraph | The implementation of raster and 2D-graphics. It is designated for work with primitive graphics such as rectangles, lines and pixels

Detailed Description

These structures and functions are used for drawing various graphical primitives and displaying them onscreen. Please pay special attention to the DisplayGraphics and Graphics structures.

Define Documentation

#define ARROW_DOWN 0x02

Arrow down.

#define ARROW_UP 0x01

Arrow up.

#define CLR_BLACK 255

Make the object black.

#define CLR_DKGRAY 171

Make the object dark gray.

#define CLR_LTGRAY 85

Make the object light gray.

#define CLR_WHITE 0

Make the object white.

#define DM_OR 1

Make the image opaque; do not allow background color to show through the object.
See set_bckcolor().

#define DM_PUT 0

Place the image as is.

#define DM_XOR 2

XOR pixels overlay bitmap pixels.

#define SCREEN_HEIGHT 100

CYBIKO screen height.

#define SCREEN_WIDTH 160

CYBIKO screen width.

Typedef Documentation

typedef int color_t

Display color.
Must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY or CLR_BLACK.

See also:
CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

typedef int drawmode_t

Drawing mode.
Must be one of the following: DM_PUT, DM_OR or DM_XOR.

See also:
DM_PUT, DM_OR, DM_XOR.

Enumeration Type Documentation

anonymous enum

Custom rectangle styles.

See also:
ARROW_UP, ARROW_DOWN.
Enumeration values:
RR_NONE | Simple rectangle.
RR_ARROWUP | Rectangle with an arrow at the top pointing up.
RR_ARROWDOWN | Rectangle with an arrow at the top pointing down.
RR_ROUND | Rectangle with rounded corners.
RR_ERASE | Clear background.

Function Documentation

void draw_bar ( | int x,
 | int y,
 | int width,
 | int height,
 | color_t color,
 | bool xor )

Fills a rectangle with a specified color, to form a color bar.

Parameters:
x | the x-coordinate of the upper-left corner
y | the y-coordinate of the upper-left corner
width | the bar's width
height | the bar's height
color | the bar's color
xor | if TRUE xor operation will be performed
Returns:
None.
        #include <cywin.h>
        ...
        draw_bar( 10, 10, 100, 100, CLR_DKGRAY, FALSE );
        ...

void draw_roundrect ( | struct Graphics * ptr_graphics,
 | struct rect_t * ptr_rectangle,
 | int style,
 | char * sz_caption )

Draws a custom rectangle with caption.
There are five rectangle styles: RR_NONE, RR_ARROWUP, RR_ARROWDOWN, RR_ROUND and RR_ERASE.

Parameters:
ptr_graphics | a pointer to an initialized Graphics object.
ptr_rectangle | a pointer to the bounding rectangle.
style | the rectangle's style.
sz_caption | the rectangle's caption.
Returns:
None.
        #include <cywin.h>
        ...
        struct rect_t rect;
        struct module_t main_module;
        ...
        init_module( &main_module );
        rect_set( &rect, 10, 10, 100, 100 );
        ...
        draw_roundrect( main_module.m_gfx, &rect, RR_ROUND, "Rect caption" );
        ...

bool in_rect ( | int x,
 | int y,
 | struct rect_t * ptr_rectangle )

Returns TRUE if the point is in the rectangle area.

Parameters:
x | the point's x-coordinate.
y | the point's y-coordinate.
ptr_rectangle | the pointer to the rectangle.
Returns:
TRUE if the point is in the rectangle.
        #include <cywin.h>
        ...
        int x;
        int y;
        struct rect_t rect_screen;
        ...
        rect_set( &rect_screen, 0, 0, 160, 100 );
        ...
        if ( !in_rect( x, y, &rect_screen ) )
        {
          TRACE( "Warning: Object is out of screen.");
        }
        ...

void rect ( | int x,
 | int y,
 | int width,
 | int height,
 | color_t color )

Draws a rectangle with the specified color.

Parameters:
x | the x-coordinate of the upper-left corner.
y | the y-coordinate of the upper-left corner.
width | the rectangle's width.
height | the rectangle's height.
color | the rectangle's color.
Returns:
None.
        #include <cywin.h>
        ...
        rect( 10, 10, 100, 100, CLR_DKGRAY );
        ...


DisplayGraphics Struct Reference

Inheritance diagram for DisplayGraphics

Collaboration diagram for DisplayGraphics:

Public Methods
void | DisplayGraphics_draw_bitmap (struct DisplayGraphics *ptr_gfx, struct Bitmap *bmp, int left, int top, int fm)
int | DisplayGraphics_draw_char (struct DisplayGraphics *ptr_gfx, int fx, int fy, char_t fc)
void | DisplayGraphics_draw_hline (struct DisplayGraphics *ptr_gfx, int x, int y, int xx)
void | DisplayGraphics_draw_vline (struct DisplayGraphics *ptr_gfx, int x, int y, int yy)
void | DisplayGraphics_draw_line (struct DisplayGraphics *ptr_gfx, int x, int y, int xx, int yy)
void | DisplayGraphics_draw_rect (struct DisplayGraphics *ptr_gfx, int fx, int fy, int fw, int fh)
void | DisplayGraphics_draw_rect_Ex (struct DisplayGraphics *ptr_gfx, struct rect_t *ptr_rectangle)
void | DisplayGraphics_draw_text (struct DisplayGraphics *ptr_gfx, char *text, int left, int top)
void | DisplayGraphics_draw_text_Ex (struct DisplayGraphics *ptr_gfx, char *text, int left, int top, int flen)
void | DisplayGraphics_fill_rect (struct DisplayGraphics *ptr_gfx, int fx,int fy, int fw, int fh)
void | DisplayGraphics_fill_rect_Ex (struct DisplayGraphics *ptr_gfx, struct rect_t *ptr_rectangle)
void | DisplayGraphics_fill_screen (struct DisplayGraphics *ptr_gfx, color_t fc)
void | DisplayGraphics_flip (struct DisplayGraphics *ptr_gfx)
int | DisplayGraphics_get_char_height (struct DisplayGraphics *ptr_gfx)
int | DisplayGraphics_get_char_width (struct DisplayGraphics *ptr_gfx)
void | DisplayGraphics_get_clip (struct DisplayGraphics *ptr_gfx, struct rect_t *ptr_rectangle)
color_t | DisplayGraphics_get_color (struct DisplayGraphics *ptr_gfx)
drawmode_t | DisplayGraphics_get_draw_mode (struct DisplayGraphics *ptr_gfx)
struct Font* | DisplayGraphics_get_font (struct DisplayGraphics *ptr_gfx)
int | DisplayGraphics_get_page (struct DisplayGraphics *ptr_gfx)
int | DisplayGraphics_get_bytes_total (struct DisplayGraphics *ptr_gfx)
char* | DisplayGraphics_get_page_ptr (struct DisplayGraphics *ptr_gfx, int page)
color_t | DisplayGraphics_get_pixel (struct DisplayGraphics *ptr_gfx, int fx, int fy)
int | DisplayGraphics_string_width (struct DisplayGraphics *ptr_gfx, char *string)
int | DisplayGraphics_string_width_Ex (struct DisplayGraphics *ptr_gfx, char *string, int flen)
void | DisplayGraphics_page_copy (struct DisplayGraphics *ptr_gfx, int from_page, int to_page, int x, int y, int w, int h)
void | DisplayGraphics_page_copy_Ex (struct DisplayGraphics *ptr_gfx, int from_page, int to_page, struct rect_t *rc)
void | DisplayGraphics_scroll (struct DisplayGraphics *ptr_gfx, struct rect_t *ptr_rectangle, int dx, int dy)
void | DisplayGraphics_set_bitmap (struct DisplayGraphics *ptr_gfx, struct Bitmap *bmp)
void | DisplayGraphics_put_background (struct DisplayGraphics *ptr_gfx, char *ptr_background)
char* | DisplayGraphics_get_buf_addr (struct DisplayGraphics *ptr_gfx)
void | DisplayGraphics_set_bkcolor (struct DisplayGraphics *ptr_gfx, color_t fc)
void | DisplayGraphics_set_clip (struct DisplayGraphics *ptr_gfx, int fx, int fy, int fw, int fh)
void | DisplayGraphics_set_clip_Ex (struct DisplayGraphics *ptr_gfx, struct rect_t *ptr_rectangle)
void | DisplayGraphics_set_color (struct DisplayGraphics *ptr_gfx, color_t fc)
void | DisplayGraphics_set_draw_mode (struct DisplayGraphics *ptr_gfx, drawmode_t dm)
void | DisplayGraphics_set_font (struct DisplayGraphics *ptr_gfx, struct Font *font)
void | DisplayGraphics_set_pixel (struct DisplayGraphics *ptr_gfx, int fx, int fy, color_t fc)
void | DisplayGraphics_set_page (struct DisplayGraphics *ptr_gfx, int page)
void | DisplayGraphics_show (struct DisplayGraphics *ptr_gfx)
void | DisplayGraphics_show_Ex (struct DisplayGraphics *ptr_gfx, int page)

Detailed Description

See also:
Drawing Primitives and Screen Manipulation

Member Function Documentation

void DisplayGraphics_draw_bitmap ( | struct DisplayGraphics * ptr_gfx,
 | struct Bitmap * bmp,
 | int left,
 | int top,
 | int fm )

Draws a bitmap 'bmp' in a specified position (left, top) in 'fm' mode.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
bmp | A pointer to the initialized Bitmap object
left | x-coordinate of the left side of the bitmap to be drawn
top | y-coordinate of the top side of the bitmap to be drawn
fm | A drawing mode
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Bitmap bitmap;
     ...
     init_module( &main_module );
     Bitmap_ctor_Ex1( &bitmap, "screen.pic" );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     DisplayGraphics_draw_bitmap( main_module.m_gfx, &bitmap, 30, 40, BM_NORMAL );
     ...

int DisplayGraphics_draw_char ( | struct DisplayGraphics * ptr_gfx,
 | int fx,
 | int fy,
 | char_t fc )

Draws a character 'fc' with the current font in a specified position (fx, fy).

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
fx | x-coordinate of the character to be drawn
fy | y-coordinate of the character to be drawn
fc | A character to be drawn
Returns:
The position of the next pixel after the 'fc' character
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     Graphics_set_font( main_module.m_gfx, cool_normal_font);
     pos = Graphics_draw_char( main_module.m_gfx, 10, 10, 'c' );
     ...

void DisplayGraphics_draw_hline ( | struct DisplayGraphics * ptr_gfx,
 | int x,
 | int y,
 | int xx )

Draws a horizontal line from point (x , y) to point (xx , y).

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
x | x-coordinate horizontal line's starting point
y | y-coordinate horizontal line's starting point
xx | x-coordinate horizontal line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_draw_hline( main_module.m_gfx, 10, 10, 20);
     ...
See also:
DisplayGraphics_draw_line, DisplayGraphics_draw_vline.

void DisplayGraphics_draw_line ( | struct DisplayGraphics * ptr_gfx,
 | int x,
 | int y,
 | int xx,
 | int yy )

Draws a solid line from point (x,y) to point (xx,yy).

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
x | x-coordinate of the line's starting point
y | y-coordinate of the line's starting point
xx | x-coordinate of the line's finishing point
yy | y-coordinate of the line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_draw_line( main_module.m_gfx, 10, 10, 20, 20);
     ...
See also:
DisplayGraphics_draw_vline, DisplayGraphics_draw_hline.

void DisplayGraphics_draw_rect ( | struct DisplayGraphics * ptr_gfx,
 | int fx,
 | int fy,
 | int fw,
 | int fh )

Draws a rectangular frame in the current color.
It is defined by the coordinates stored in the fx, fy, fw and fh parameters.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
fx | The rectangle's left coordinate
fy | The rectangle's top coordinate
fw | The rectangle's width
fh | The rectangle's height
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_draw_rect( main_module.m_gfx, 10, 10, 20, 20);
     ...
See also:
DisplayGraphics_draw_rect_Ex.

void DisplayGraphics_draw_rect_Ex ( | struct DisplayGraphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Duplicates the DisplayGraphics_draw_rect function.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
ptr_rectangle | A pointer to a rect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t rectangle={0,0,100,100};
     ...
     init_module( &main_module );
     Graph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_draw_rect_Ex( main_module.m_gfx, &rect_t);
     ...
See also:
DisplayGraphics_draw_rect.

void DisplayGraphics_draw_text ( | struct DisplayGraphics * ptr_gfx,
 | char * text,
 | int left,
 | int top )

Draws text in a specified position (left, top) with the current font.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
text | A pointer to the string to be drawn
left | x-coordinate of the text to be drawn
top | y-coordinate of the text to be drawn
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_draw_text( main_module.m_gfx, "Any text", 10, 10 );
     ...
See also:
DisplayGraphics_draw_text_Ex.

void DisplayGraphics_draw_text_Ex ( | struct DisplayGraphics * ptr_gfx,
 | char * text,
 | int left,
 | int top,
 | int flen )

Duplicates the DisplayGraphics_draw_text function.
If the length of the string exceeds the number of 'flen' pixels, the string will be truncated.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
text | A pointer to the string to be drawn
left | x-coordinate of the text to be drawn
top | y-coordinate of the text to be drawn
flen | Maximum length (in pixels) of the string to be drawn
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_draw_text_Ex( main_module.m_gfx, "Any text", 10, 10, 20);
     ...
See also:
DisplayGraphics_draw_text.

void DisplayGraphics_draw_vline ( | struct DisplayGraphics * ptr_gfx,
 | int x,
 | int y,
 | int yy )

Draws a vertical line from point (x, y) to point (x , yy).

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
x | x-coordinate of the vertical line's starting point
y | y-coordinate of the vertical line's starting point
yy | y-coordinate of the vertical line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_draw_vline( main_module.m_gfx, 10, 10, 20);
     ...
See also:
DisplayGraphics_draw_line, DisplayGraphics_draw_hline.

void DisplayGraphics_fill_rect ( | struct DisplayGraphics * ptr_gfx,
 | int fx,
 | int fy,
 | int fw,
 | int fh )

Fills a rectangle with the current color.
The rectangle's area is defined by the fx, fy, fw and fh parameters.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
fx | The rectangle's left coordinate
fy | The rectangle's top coordinate
fw | The rectangle's width
fh | The rectangle's height
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_fill_rect( main_module.m_gfx, 10, 10, 20, 20);
     ...
See also:
DisplayGraphics_fill_rect_Ex.

void DisplayGraphics_fill_rect_Ex ( | struct DisplayGraphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Duplicates the Graphics_fill_rect function.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
ptr_rectangle | A pointer to a tect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t rectangle={0,0,100,100};
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     DisplayGraphics_fill_rect_Ex( main_module.m_gfx, &rect_t);
     ...
See also:
Graphics_fill_rect.

void DisplayGraphics_fill_screen ( | struct DisplayGraphics * ptr_gfx,
 | color_t fc )

Fills the screen with the 'fc' color.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
fc | A color's value
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     DisplayGraphics_fill_screen( main_module.m_gfx, CLR_LTGRAY);
     ...
See also:
CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void DisplayGraphics_flip ( struct DisplayGraphics * ptr_gfx )

Switches background and foreground pages and shows the background screen on the LCD.

Parameters:
ptr_gfx A pointer to the initialized DisplayGraphics object
Returns:
None
   #include <cybiko.h>
     ...
     int i;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     DisplayGraphics_set_page( main_module.m_gfx, 0 );
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_WHITE );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
     ...
     DisplayGraphics_set_page( main_module.m_gfx, 1 );
     TGraph_set_color( main_module.m_gfx, CLR_BLACK );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     DisplayGraphics_show( main_module.m_gfx );
     ...
     for(i = 0; i < 20 ; i++)
     {
       DisplayGraphics_flip( main_module.m_gfx );
       cWinApp_pause( main_module.m_gfx , 250 );   // 250 milliseconds delay.
     }
     //  Black and white rectangles will change places with each other.

char * DisplayGraphics_get_buf_addr ( struct DisplayGraphics * ptr_gfx )

Returns a pointer to an image of the DisplayGraphics object destination.

Parameters:
ptr_gfx A pointer to a DisplayGraphics object
Returns:
A pointer to an image of the DisplayGraphics object destination
See also:
DisplayGraphics_page_copy_Ex.

int DisplayGraphics_get_bytes_total ( struct DisplayGraphics * ptr_gfx )

Returns the number of bytes amount in the screen buffer.

Parameters:
ptr_gfx A pointer to the initialized DisplayGraphics object
Returns:
The number of bytes in the screen buffer
   #include <cybiko.h>
     ...
     struct module_t main_module;
     char* ptr_display_buffer;
     ...
     init_module( &main_module );
     ptr_display_buffer = (char* ) malloc( DisplayGraphics_get_bytes_total( main_module.m_gfx ) );
     ...

int DisplayGraphics_get_char_height ( struct DisplayGraphics * ptr_gfx )

Returns the current font's character's height.

Parameters:
ptr_gfx A pointer to the initialized DisplayGraphics object
Returns:
Current font's character height
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     DisplayGraphics_set_font( main_module.m_gfx, cool_normal_font );
     font_height = DisplayGraphics_get_char_height( main_module.m_gfx );
     ...

int DisplayGraphics_get_char_width ( struct DisplayGraphics * ptr_gfx )

Returns the current font's character width.

Parameters:
ptr_gfx A pointer to the initialized DisplayGraphics object
Returns:
Current font's character width
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     DisplayGraphics_set_font( main_module.m_gfx, cool_normal_font );
     font_height = DisplayGraphics_get_char_width( main_module.m_gfx );
     ...

void DisplayGraphics_get_clip ( | struct DisplayGraphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Returns a clip region.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
ptr_rectangle | A pointer to a rect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct rect_t clip_region;
     ...
     DisplayGraphics_get_clip( main_module.m_gfx, &clip_region)
     ...

color_t DisplayGraphics_get_color ( struct DisplayGraphics * ptr_gfx )

Returns the current foreground color.

Parameters:
ptr_gfx A pointer to the initialized DisplayGraphics object
Returns:
Current foreground color
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     if ( DisplayGraphics_get_color( main_module.m_gfx ) != CLR_LTGRAY )
       DisplayGraphics_set_color( main_module.m_gfx, CLR_LTGRAY);
     ...
See also:
DisplayGraphics_set_color, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

drawmode_t DisplayGraphics_get_draw_mode ( struct DisplayGraphics * ptr_gfx )

Returns the current draw mode.

Parameters:
ptr_gfx A pointer to the initialized DisplayGraphics object
Returns:
Current draw mode
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     if ( DisplayGraphics_get_draw_mode( main_module.m_gfx ) != DM_PUT )
       DisplayGraphics_set_draw_mode( main_module.m_gfx, DM_PUT);
     ...
See also:
DisplayGraphics_set_draw_mode, DM_PUT, DM_OR, DM_XOR.

struct Font * DisplayGraphics_get_font ( struct DisplayGraphics * ptr_gfx )

Returns the current font.

Parameters:
ptr_gfx A pointer to the initialized DisplayGraphics object
Returns:
A pointer to the current font
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Font *curFont;
     ...
     init_module( &main_module );
     curFont=DisplayGraphics_get_font( main_module.m_gfx);
     ...

int DisplayGraphics_get_page ( struct DisplayGraphics * ptr_gfx )

Returns the current graphics page number (0 or 1).

Parameters:
ptr_gfx A pointer to a Graphics object
Returns:
Current graphics page number (0 or 1)
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     if ( !DisplayGraphics_get_page( main_module.m_gfx ) )
       DisplayGraphics_set_page( main_module.m_gfx, 1 );
     ...
See also:
DisplayGraphics_flip, DisplayGraphics_set_page.

char * DisplayGraphics_get_page_ptr ( | struct DisplayGraphics * ptr_gfx,
 | int page )

Returns the pointer to the screen buffer for the 'fp' graphics page.
Use with caution!!!

Parameters:
ptr_gfx | A pointer to a DisplayGraphics object
page | A number of the graphics page
Returns:
A pointer to the graphics page's screen buffer
   #include <cybiko.h>
     ...
     struct module_t main_module;
     char*  ptr_display_buffer;
     init_module( &main_module );
     ...
     // Allocating memory for buffer
     ptr_display_buffer = (char* ) malloc( TGraph_get_bytes_total( main_module.m_gfx ) );
     ...
     // Make some graphics operations ( draw a picture, for instance)
     ...
     // Save the screen
     memcpy( ptr_display_buffer, DisplayGraphics_get_page_ptr(main_module.m_gfx, 0), TGraph_get_bytes_total(main_module.m_gfx));
     ...
     // Make another graphics operation
     ...
     // Restore the screen. Works very fast.
     TGraph_put_background( main_module.m_gfx, ptr_display_buffer );
     ...
     // Make another graphics operation
     ...
     // Restore the screen again.
     TGraph_put_background( main_module.m_gfx, ptr_display_buffer );
     ...
     free( ptr_display_buffer );

color_t DisplayGraphics_get_pixel ( | struct DisplayGraphics * ptr_gfx,
 | int fx,
 | int fy )

Returns the color of the pixel with coordinate (fx , fy).

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
fx | x-coordinate of the required pixel
fy | y-coordinate of the required pixel
Returns:
The color of the pixel with coordinate (fx , fy)
   #include <cybiko.h>
     ...
     struct module_t main_module;
     if ( DisplayGraphics_get_pixel( main_module.m_gfx, 10, 30 ) == CLR_BLACK )
          DisplayGraphics_set_pixel( main_module.m_gfx, 10, 30, CLR_WHITE );
       ...
See also:
DisplayGraphics_set_pixel.

void DisplayGraphics_page_copy ( | struct DisplayGraphics * ptr_gfx,
 | int from_page,
 | int to_page,
 | int x,
 | int y,
 | int w,
 | int h )

Copies a rectangular area from one graphics page to another.
A rectangular area is defined by x,y,h and w parameters.

Parameters:
ptr_gfx | A pointer to a DisplayGraphics object
from_page | The source page to copy
to_page | The destination page for the copied image
x | x-coordinate of the rectangular area to be copied
y | y-coordinate of the rectangular area to be copied
w | A width of the page to be copied
h | A height of the page to be copied
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx A pointer to the Cybiko graphics context
     DisplayGraphics_set_page( main_module.m_gfx, 1 );
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_WHITE );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show_Ex( main_module.m_gfx , 1 );
     ...
     DisplayGraphics_set_page( main_module.m_gfx, 0 );
     DisplayGraphics_page_copy( main_module.m_gfx, 1, 0, 5, 5, 30, 30 );
     // Now the white rectangle is on both Cybiko graphics pages.
     ...
See also:
DisplayGraphics_page_copy_Ex.

void DisplayGraphics_page_copy_Ex ( | struct DisplayGraphics * ptr_gfx,
 | int from_page,
 | int to_page,
 | struct rect_t * rc )

Duplicates the DisplayGraphics_page_copy function.
The region coordinates are defined in the rect_t object.

Parameters:
ptr_gfx | A pointer to a DisplayGraphicsGraphics object
from_page | The source page to copy
to_page | The destination page for the copied image
rc | A pointer to the rectangle to be copied
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t white_rect;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     DisplayGraphics_set_page( main_module.m_gfx, 1 );
     white_rect.x = 5;
     white_rect.y = 5;
     white_rect.w = 30;
     white_rect.h = 30;
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_WHITE );
     TGraph_fill_rect_Ex( main_module.m_gfx, &white_rect );
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show_Ex( main_module.m_gfx , 1 );
     ...
     DisplayGraphics_set_page( main_module.m_gfx, 0 );
     DisplayGraphics_page_copy_Ex( main_module.m_gfx, 1, 0 , &white_rect );
     // Now the white rectangle is on both Cybiko graphics pages.
See also:
DisplayGraphics_page_copy.

void DisplayGraphics_put_background ( | struct DisplayGraphics * ptr_gfx,
 | char * ptr_background )

Sets an image pointed by ptr_background as a background image.

Parameters:
ptr_gfx | A pointer to a DisplayGraphics object
ptr_background | A pointer to a background image
Returns:
None
   #include <cywin.h>
     ...
     struct module_t main_module;
     struct Graphics gfx;
     ...
     init_module( &main_module );
     ...
     DisplayGraphics_put_background( main_module.m_gfx,
              Graphics_get_buf_addr( &gfx ));
     ...

void DisplayGraphics_scroll ( | struct DisplayGraphics * ptr_gfx,
 | struct rect_t * ptr_rectangle,
 | int dx,
 | int dy )

Scrolls a rectangular area by dx and dy.

Parameters:
ptr_gfx | A pointer to a DisplayGraphics object
ptr_rectangle | A pointer to the rect_t type structure to be scrolled
dx | A number of pixels in the x-direction
dy | A number of pixels in the y-direction
Returns:
None
   #include <cywin.h>
     ...
     struct module_t main_module;
     int scroll_shift;
     ...
     init_module( &main_module );
     ...
     DisplayGraphics_scroll( main_module.m_gfx, 0, 0, 160, 78, scroll_shift, 0 );
     ...

void DisplayGraphics_set_bitmap ( | struct DisplayGraphics * ptr_gfx,
 | struct Bitmap * bmp )

Sets a bitmap 'bmp' as the destination for drawings.

Parameters:
ptr_gfx | A pointer to a DisplayGraphics object
bmp | A pointer to the Bitmap object
Returns:
None
   #include <cywin.h>
     ...
     struct module_t main_module;
     struct Bitmap bitmap;
     ...
     init_module( &main_module );
     ...
     DisplayGraphics_set_bitmap( main_module.m_gfx, &bitmap );
     ...
     DisplayGraphics_show( main_module.m_gfx );
     ...

void DisplayGraphics_set_bkcolor ( | struct DisplayGraphics * ptr_gfx,
 | color_t fc )

Sets the current background color.

Parameters:
ptr_gfx | A pointer to a TGraph object
fc | A color_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Bitmap bmp;
     ...
     init_module( &main_module );
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     ...
     // Set draw mode to mode OR.
     TGraph_set_draw_mode( main_module.m_gfx, DM_OR );
     // Set transparent color to CLR_BLACK
     TGraph_set_bkcolor( main_module.m_gfx, CLR_BLACK );
     // Draw all pixels of the bitmap except pixels with CLR_BLACK color.
     Graphics_draw_bitmap( main_module.m_gfx, &bmp, 30, 40, BM_NORMAL );
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...
See also:
CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void DisplayGraphics_set_clip ( | struct DisplayGraphics * ptr_gfx,
 | int fx,
 | int fy,
 | int fw,
 | int fh )

Sets a clip region, defined by coordinates that are stored in fx, fy, fw and fh parameters.

Parameters:
ptr_gfx | A pointer to a TGraph object
fx | x-coordinate of upper-left corner of the area to be clipped
fy | y-coordinate of upper-left corner of the area to be clipped
fw | Width of the area to be clipped
fh | Height of the area to be clipped
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
        ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
         TGraph_set_clip( main_module.m_gfx, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT );
     ...
See also:
DisplayGraphics_set_clip_Ex.

void DisplayGraphics_set_clip_Ex ( | struct DisplayGraphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Duplicates the Graphics_set_clip function.
The region coordinates are stored in the rect_t object.

Parameters:
ptr_gfx | A pointer to a TGraph object
ptr_rectangle | A pointer to a rect_t object. By this structure we can define the region coordinates
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     struct rect_t new_clip_reg;
     init_module( &main_module );
     ...
     new_clip_reg.x = 10;
     new_clip_reg.y = 10;
     new_clip_reg.h = 100;
     new_clip_reg.w = 100;
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
        ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
        TGraph_set_clip( main_module.m_gfx, &new_clip_reg );
     ...
See also:
DisplayGraphics_set_clip.

void DisplayGraphics_set_color ( | struct DisplayGraphics * ptr_gfx,
 | color_t fc )

Sets the current foreground color.

Parameters:
ptr_gfx | A pointer to a TGraph object
fc | A pointer to a color_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.
     if ( TGraph_get_color( main_module.m_gfx ) != CLR_LTGRAY )
          TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_draw_line( main_module.m_gfx, 10, 10, 20, 60 );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
DisplayGraphics_get_color, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void DisplayGraphics_set_draw_mode ( | struct DisplayGraphics * ptr_gfx,
 | drawmode_t dm )

Sets the current drawing mode.

Parameters:
ptr_gfx | A pointer to a TGraph object
dm | A drawmode_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     ...
     // The second parameter in the TGraph_set_draw_mode function is the draw mode value.
     // This value must be one of the following: DM_XOR, DM_OR, DM_PUT.
     if ( TGraph_get_draw_mode( main_module.m_gfx ) != DM_PUT )
          TGraph_set_draw_mode( main_module.m_gfx, DM_PUT );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
DisplayGraphics_get_draw_mode, DM_XOR, DM_OR, DM_PUT.

void DisplayGraphics_set_font ( | struct DisplayGraphics * ptr_gfx,
 | struct Font * font )

Sets the font object as a current font.

Parameters:
ptr_gfx | A pointer to a TGraph object
font | A pointer to the Font structure
Returns:
None
   #include <cybiko.h>
     ...
     int str_plen;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     ...

void DisplayGraphics_set_page ( | struct DisplayGraphics * ptr_gfx,
 | int page )

Sets the page 'page' as a target for drawing, and in default sends it to the LCD.

Parameters:
ptr_gfx | A pointer to a DisplayGraphics object
page | Can be 0 or 1
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     if ( !DisplayGraphics_get_page( main_module.m_gfx ) )
        DisplayGraphics_set_page( main_module.m_gfx, 1 );
     ...
See also:
DisplayGraphics_get_page.

void DisplayGraphics_set_pixel ( | struct DisplayGraphics * ptr_gfx,
 | int fx,
 | int fy,
 | color_t fc )

Sets the color value 'fc' for pixel (fx, fy).

Parameters:
ptr_gfx | A pointer to a TGraph object
fx | x-coordinate of the pixel to be drawn
fy | y-coordinate of the pixel to be drawn
fc | Color of the pixel to be drawn
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( TGraph_get_pixel( main_module.m_gfx, 10, 30 ) == CLR_BLACK )
          TGraph_set_pixel( main_module.m_gfx, 10, 30, CLR_WHITE )
     ...
See also:
DisplayGraphics_get_pixel, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void DisplayGraphics_show ( struct DisplayGraphics * ptr_gfx )

Sends the current graphics page to the LCD.

Parameters:
ptr_gfx A pointer to a DisplayGraphics object
Returns:
None
   #include <cybiko.h>
     ...
     int i;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     DisplayGraphics_set_page( main_module.m_gfx, 0 );
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_WHITE );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
     ...
     DisplayGraphics_set_page( main_module.m_gfx, 1 );
     TGraph_set_color( main_module.m_gfx, CLR_BLACK );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     DisplayGraphics_show( main_module.m_gfx );
     ...
     for(i=0; i<20; i++)
     {
       DisplayGraphics_flip( main_module.m_gfx );
       cWinApp_pause( main_module.m_gfx, 250);   // 250 milliseconds delay.
     }
     //  Black and white rectangles will change places with each other.
See also:
DisplayGraphics_set_page, DisplayGraphics_show_Ex.

void DisplayGraphics_show_Ex ( | struct DisplayGraphics * ptr_gfx,
 | int page )

The extended version of the DisplayGraphics_show function.
Sends a specified graphics page to the LCD. The graphics page defines are in the 'pg' parameter.

Parameters:
ptr_gfx | A pointer to a DisplayGraphics object
page | Graphics page (0 or 1)
Returns:
None
   #include <cybiko.h>
     ...
     int i;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     DisplayGraphics_set_page( main_module.m_gfx, 0 );
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_WHITE );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
     ...
     DisplayGraphics_set_page( main_module.m_gfx, 1 );
     TGraph_set_color( main_module.m_gfx, CLR_BLACK );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     DisplayGraphics_show( main_module.m_gfx );
     ...
     for(i=0; i<20; i++)
     {
       DisplayGraphics_show_Ex( main_module.m_gfx, i%2 );
       cWinApp_pause(main_module.m_process , 250);   // 250 milliseconds delay.
     }
     //  Black and white rectangles will change places with each other.
See also:
DisplayGraphics_set_page, DisplayGraphics_show.

int DisplayGraphics_string_width ( | struct DisplayGraphics * ptr_gfx,
 | char * string )

Returns the width (in pixels) of a string in the current font.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
string | A pointer to the string
Returns:
The width (in pixels) of a string in the current font
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int str_plen;
     DisplayGraphics_set_font( main_module.m_gfx, cool_normal_font );
     ...
     str_plen = DisplayGraphics_string_width( main_module.m_gfx, "Any string" );
     ...
See also:
DisplayGraphics_string_width_Ex.

int DisplayGraphics_string_width_Ex ( | struct DisplayGraphics * ptr_gfx,
 | char * string,
 | int flen )

Returns the width (in pixels) of the first 'flen' symbols in a string.

Parameters:
ptr_gfx | A pointer to the initialized DisplayGraphics object
string | A pointer to the string
flen | A number of the symbols
Returns:
The width (in pixels) of the first 'flen' symbols in a string
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int str_plen;
     DisplayGraphics_set_font( main_module.m_gfx, cool_normal_font );
     ...
     str_plen = DisplayGraphics_string_width_Ex( main_module.m_gfx, "Any string" ,20);
     ...
See also:
DisplayGraphics_string_width.


Graphics Struct Reference

Inheritance diagram for Graphics

Collaboration diagram for Graphics:

Public Methods
struct Graphics* | Graphics_ctor (struct Graphics *ptr_gfx)
struct Graphics* | Graphics_ctor_Ex (struct Graphics *ptr_gfx, struct Bitmap *bitmap)
void | Graphics_dtor (struct Graphics *ptr_gfx, int memory_flag)
void | Graphics_draw_bitmap (struct Graphics *ptr_gfx, struct Bitmap *bmp, int left, int top, short fm)
int | Graphics_draw_char (struct Graphics *ptr_gfx, int x, int y, char fc)
void | Graphics_draw_text (struct Graphics *ptr_gfx, char *text, int left, int top)
void | Graphics_draw_text_Ex (struct Graphics *ptr_gfx, char *str, int left, int top, int len)
struct Bitmap* | Graphics_get_bitmap (struct Graphics *ptr_gfx)
int | Graphics_get_char_height (struct Graphics *ptr_gfx)
int | Graphics_get_char_width (struct Graphics *ptr_gfx, char chr)
struct Font* | Graphics_get_font (struct Graphics *ptr_gfx)
int | Graphics_string_width (struct Graphics *ptr_gfx, char *str)
int | Graphics_string_width_Ex (struct Graphics *ptr_gfx, char *str, int len)
void | Graphics_set_bitmap (struct Graphics *ptr_gfx, struct Bitmap *bmp)
void | Graphics_set_font (struct Graphics *ptr_gfx, struct Font *font)
void | Graphics_scroll (struct Graphics *ptr_gfx, struct rect_t *ptr_rectangle, int dx, int dy)
void | Graphics_draw_hline (struct Graphics *ptr_gfx, int x, int y, int xx)
void | Graphics_draw_vline (struct Graphics *ptr_gfx, int x, int y, int yy)
void | Graphics_draw_line (struct Graphics *ptr_gfx, int x, int y, int xx, int yy)
void | Graphics_draw_rect (struct Graphics *ptr_gfx, int fx, int fy, int fw, int fh)
void | Graphics_draw_rect_Ex (struct Graphics *ptr_gfx, struct rect_t *ptr_rectangle)
void | Graphics_fill_rect (struct Graphics *ptr_gfx, int fx,int fy, int fw, int fh)
void | Graphics_fill_rect_Ex (struct Graphics *ptr_gfx, struct rect_t *ptr_rectangle)
void | Graphics_fill_screen (struct Graphics *ptr_gfx, color_t fc)
int | Graphics_get_bytes_total (struct Graphics *ptr_gfx)
void | Graphics_set_clip (struct Graphics *ptr_gfx, int fx, int fy, int fw, int fh)
void | Graphics_get_clip (struct Graphics *ptr_gfx, struct rect_t *ptr_rectangle)
void | Graphics_set_clip_Ex (struct Graphics *ptr_gfx, struct rect_t *ptr_rectangle)
color_t | Graphics_get_color (struct Graphics *ptr_gfx)
void | Graphics_set_color (struct Graphics *ptr_gfx, color_t fc)
drawmode_t | Graphics_get_draw_mode (struct Graphics *ptr_gfx)
void | Graphics_set_draw_mode (struct Graphics *ptr_gfx, drawmode_t dm)
void | Graphics_put_background (struct Graphics *ptr_gfx, char *fp)
color_t | Graphics_get_pixel (struct Graphics *ptr_gfx, int fx, int fy)
void | Graphics_set_pixel (struct Graphics *ptr_gfx, int fx, int fy, color_t fc)
char* | Graphics_get_buf_addr (struct Graphics *ptr_gfx)
void | Graphics_set_bkcolor (struct Graphics *ptr_gfx, color_t fc)

Detailed Description

The Graphics structure uses bitmaps to maintain many operations. The DisplayGraphics structure allows you to draw operations directly on the screen. You can draw graphics primitives,as well as text with the current font.

Because TGraph is its parent structure, the Graphics structure's functions are defined in TGraph structure. For example, manipulations of graphics primitives are implemented in TGraph structure.

To use some Graphics functions, you must obtain the Display Graphics Context from the init_module function. This context has only one parameter (the main application module parameter) and it must be obtained from the module_t structure.

See examples for related functions.

See also:
Drawing Primitives and Screen Manipulation

Member Function Documentation

struct Graphics * Graphics_ctor ( struct Graphics * ptr_gfx )

Simple Graphics constructor.
Creates an empty Graphics object.

Parameters:
ptr_gfx A pointer to the Graphics structure
Returns:
A pointer to the initialized Graphics object
   #include <cybiko.h>
     ...
     struct Graphics gfx;
     Graphics_ctor( &gfx );
     ...
     Graphics_dtor( &gfx, LEAVE_MEMORY );
See also:
Graphics_ctor_Ex.

struct Graphics * Graphics_ctor_Ex ( | struct Graphics * ptr_gfx,
 | struct Bitmap * bitmap )

The extended version of the Graphics_ctor function.
Creates a Graphics object that is associated with a Bitmap object.

Parameters:
ptr_gfx | A pointer to a Graphics object
bitmap | A pointer to a Bitmap object
Returns:
A pointer to the initialized Graphics object
   #include <cybiko.h>
     ...
     struct Bitmap  bitmap;
     struct Graphics gfx;
     ...
     Bitmap_ctor_Ex1( &bitmap, "screen.pic" );
     Graphics_ctor_Ex( &gfx, &bitmap );
     ...
     Graphics_dtor( &gfx, LEAVE_MEMORY );
     Bitmap_dtor( &bitmap, LEAVE_MEMORY );
See also:
Graphics_ctor.

void Graphics_draw_bitmap ( | struct Graphics * ptr_gfx,
 | struct Bitmap * bmp,
 | int left,
 | int top,
 | short fm )

Allows the bitmap 'bmp' to be drawn in a specified position (left, top) in 'fm' mode.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
bmp | A pointer to the initialized Bitmap object
left | x-coordinate of the point where bitmap will be placed
top | y-coordinate of the point where bitmap will be placed
fm | Drawing mode
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Bitmap bitmap;
     ...
     init_module( &main_module );
     Bitmap_ctor_Ex1( &bitmap, "screen.pic" );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_draw_bitmap( main_module.m_gfx, &bitmap, 30, 40, BM_NORMAL );
     ...
See also:
BM_NORMAL, BM_INVERSE, BM_FLIP_X, BM_FLIP_Y.

int Graphics_draw_char ( | struct Graphics * ptr_gfx,
 | int x,
 | int y,
 | char fc )

Allows the character 'fc' to be drawn in the current font in specified position (x, y).

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
x | x-coordinate of the point where the char will be places
y | y-coordinate of the point where the char will be places
fc | A char to be drawn
Returns:
The position of the next pixel after the 'fc' character
   #include <cybiko.h>
     ...
     int pos;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     pos = Graphics_draw_char( main_module.m_gfx, 10, 10, 'c' );
     ...
See also:
Graphics_draw_text.

void Graphics_draw_hline ( | struct Graphics * ptr_gfx,
 | int x,
 | int y,
 | int xx )

Draws a horizontal line from point (x , y) to point (xx , y).

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
x | x-coordinate of the horizontal line's starting point
y | y-coordinate of the horizontal line's starting point
xx | x-coordinate of the horizontal line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     Graphics_draw_hline( main_module.m_gfx, 10, 10, 20, 60 );
     ...
See also:
Graphics_draw_line, Graphics_draw_vline.

void Graphics_draw_line ( | struct Graphics * ptr_gfx,
 | int x,
 | int y,
 | int xx,
 | int yy )

Draws a solid line from point ( x , y ) to point ( xx , yy ).

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
x | x-coordinate of the line's starting point
y | y-coordinate of the line's starting point
xx | x-coordinate of the line's finishing point
yy | y-coordinate of the line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     Graphics_draw_line( main_module.m_gfx, 10, 10, 20, 20);
     ...
See also:
Graphics_draw_vline, Graphics_draw_hline.

void Graphics_draw_rect ( | struct Graphics * ptr_gfx,
 | int fx,
 | int fy,
 | int fw,
 | int fh )

Draws a rectangular frame in the current color.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
fx | The rectangle's left coordinate
fy | The rectangle's top coordinate
fw | The rectangle's width
fh | The rectangle's height
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     Graphics_draw_rect( main_module.m_gfx, 10, 10, 20, 20);
     ...
See also:
Graphics_draw_rect_Ex.

void Graphics_draw_rect_Ex ( | struct Graphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Duplicates the Graphics_draw_rect function.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
ptr_rectangle | A pointer to a tect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t rectangle={0,0,100,100};
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     Graphics_draw_rect_Ex( main_module.m_gfx, &rect_t);
     ...
See also:
Graphics_draw_rect.

void Graphics_draw_text ( | struct Graphics * ptr_gfx,
 | char * text,
 | int left,
 | int top )

Allows 'text' to be drawn in the current font, in the specified position (left , top).

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
text | A pointer to the string to be drawn
left | x-coordinate of the string to be drawn
top | y-coordinate of the string to be drawn
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     Graphics_draw_text( main_module.m_gfx, "Any text", 10, 10 );
     ...
See also:
Graphics_draw_text_Ex, Graphics_draw_char.

void Graphics_draw_text_Ex ( | struct Graphics * ptr_gfx,
 | char * str,
 | int left,
 | int top,
 | int len )

Duplicates the Graphics_draw_text function.
If the length of the string exceeds the number of 'flen' pixels, the string will be truncated.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
str | A pointer to the string to be drawn
left | x-coordinate of the place where the string to be drawn
top | y-coordinate of the place where the string to be drawn
len | A maximum number of chars to draw
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     Graphics_draw_text_Ex( main_module.m_gfx, "Any Text", 10, 10, 20 );
     ...
See also:
Graphics_draw_text.

void Graphics_draw_vline ( | struct Graphics * ptr_gfx,
 | int x,
 | int y,
 | int yy )

Draws a vertical line from point (x , y) to point (x , yy).

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
x | x-coordinate of the vertical line's starting point
y | y-coordinate of the vertical line's starting point
yy | y-coordinate of the vertical line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     Graphics_draw_vline( main_module.m_gfx, 10, 10, 20);
     ...
See also:
Graphics_draw_line, Graphics_draw_hline.

void Graphics_dtor ( | struct Graphics * ptr_gfx,
 | int memory_flag )

Deletes a Graphics object.

Parameters:
ptr_gfx | A pointer to the Graphics structure
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
   #include <cybiko.h>
     ...
     struct Graphics gfx;
     Graphics_ctor( &gfx );
     ...
     Graphics_dtor( &gfx, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

void Graphics_fill_rect ( | struct Graphics * ptr_gfx,
 | int fx,
 | int fy,
 | int fw,
 | int fh )

Fills a rectangle with the current color.
The rectangle is defined by fx, fy, fw, and fh parameters.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
fx | The rectangle's left coordinate
fy | The rectangle's top coordinate
fw | The rectangle's width
fh | The rectangle's height
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     int pos;
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     Graphics_fill_rect( main_module.m_gfx, 10, 10, 20, 20);
     ...
See also:
Graphics_fill_rect_Ex.

void Graphics_fill_rect_Ex ( | struct Graphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Duplicates the Graphics_fill_rect function.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
ptr_rectangle | A pointer to a tect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t rectangle={0,0,100,100};
     ...
     init_module( &main_module );
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     Graphics_fill_rect_Ex( main_module.m_gfx, &rect_t);
     ...
See also:
Graphics_fill_rect.

void Graphics_fill_screen ( | struct Graphics * ptr_gfx,
 | color_t fc )

Fills the screen with the 'fc' color.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
fc | A value of the color
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     Graphics_fill_screen( main_module.m_gfx, CLR_LTGRAY);
     ...
See also:
CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

struct Bitmap * Graphics_get_bitmap ( struct Graphics * ptr_gfx )

Returns the current Bitmap context for drawing.

Parameters:
ptr_gfx A pointer to the initialized Graphics object
Returns:
A pointer to the current Graphics page's Bitmap object
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Bitmap * bitmap;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     bitmap = Graphics_get_bitmap( main_module.m_gfx );
     ...
See also:
Graphics_set_bitmap.

char * Graphics_get_buf_addr ( struct Graphics * ptr_gfx )

Returns a pointer to the Graphics object's associated image.

Parameters:
ptr_gfx A pointer to the initialized Graphics object
Returns:
A pointer to the Graphics object's associated image.
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Graphics gfx_fp;
     ...
     Graphics_put_background( main_module.m_gfx,
       Graphics_get_buf_addr( &gfx_fp )) ;
     ...

int Graphics_get_bytes_total ( struct Graphics * ptr_gfx )

Returns the total number of bytes in the screen buffer.

Parameters:
ptr_gfx A pointer to the initialized Graphics object
Returns:
The total number of bytes in the screen buffer
   #include <cybiko.h>
     ...
     struct module_t main_module;
     char* ptr_display_buffer;
     ...
     init_module( &main_module );
     ptr_display_buffer = (char* ) malloc( Graphics_get_bytes_total( main_module.m_gfx ) );
     ...

int Graphics_get_char_height ( struct Graphics * ptr_gfx )

Returns the current font's height.

Parameters:
ptr_gfx A pointer to the initialized Graphics object
Returns:
The current font's height
   #include <cybiko.h>
     ...
     int font_height;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     font_height = Graphics_get_char_height( main_module.m_gfx );
     ...
See also:
Graphics_get_char_width, Graphics_get_font.

int Graphics_get_char_width ( | struct Graphics * ptr_gfx,
 | char chr )

Returns the current font's character width.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
chr | A character
Returns:
The current font's character width
   #include <cybiko.h>
     ...
     int char_width;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     char_width = Graphics_get_char_width( main_module.m_gfx, 'g' );
     ...
See also:
Graphics_get_char_height, Graphics_get_font.

void Graphics_get_clip ( | struct Graphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Returns a clip region.
It is defined by coordinates that are stored in a rect_t object.

Parameters:
ptr_gfx | A pointer to a Graphics object
ptr_rectangle | A pointer to a rect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_clip ( main_module.m_gfx, &clip_region );
     if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
          ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
           Graphics_set_clip( main_module.m_gfx, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT );
     ...
See also:
Graphics_set_clip.

color_t Graphics_get_color ( struct Graphics * ptr_gfx )

Returns the current foreground color.

Parameters:
ptr_gfx A pointer to the initialized Graphics object
Returns:
The current foreground color
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     if ( Graphics_get_color( main_module.m_gfx ) != CLR_LTGRAY )
     Graphics_set_color( main_module.m_gfx, CLR_LTGRAY);
     ...
See also:
Graphics_set_color.

drawmode_t Graphics_get_draw_mode ( struct Graphics * ptr_gfx )

Returns the current draw mode.

Parameters:
ptr_gfx A pointer to the initialized Graphics object
Returns:
The current draw mode
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     if ( Graphics_get_draw_mode( main_module.m_gfx ) != DM_PUT )
     Graphics_set_draw_mode( main_module.m_gfx, DM_PUT);
     ...
See also:
Graphics_set_draw_mode, DM_PUT, DM_OR, DM_XOR.

struct Font * Graphics_get_font ( struct Graphics * ptr_gfx )

Returns the current font.

Parameters:
ptr_gfx A pointer to the initialized Graphics object
Returns:
A pointer to the current font
   #include <cybiko.h>
     ...
     struct Font * ptr_font;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     ...
     ptr_font = Graphics_get_font( main_module.m_gfx );
     ...
See also:
Graphics_set_font.

color_t Graphics_get_pixel ( | struct Graphics * ptr_gfx,
 | int fx,
 | int fy )

Returns the color of the pixel with coordinate ( fx , fy ).

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
fx | An x-coordinate of the required pixel
fy | An y-coordinate of the required pixel
Returns:
The color of the pixel with coordinate ( fx , fy )
   #include <cybiko.h>
     ...
     struct module_t main_module;
     if ( Graphics_get_pixel( main_module.m_gfx, 10, 30 ) == CLR_BLACK )
          Graphics_set_pixel( main_module.m_gfx, 10, 30, CLR_WHITE );
     ...
See also:
Graphics_set_pixel.

void Graphics_put_background ( | struct Graphics * ptr_gfx,
 | char * fp )

Treats fp as a pointer to a background image and sends the image to its destination.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
fp | A pointer to the background image
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Graphics gfx_fp;
     ...
     Graphics_put_background( main_module.m_gfx,
                              Graphics_get_buf_addr( &gfx_fp )) ;
     ...

void Graphics_scroll ( | struct Graphics * ptr_gfx,
 | struct rect_t * ptr_rectangle,
 | int dx,
 | int dy )

Scrolls a rectangle area that is defined by delta x, delta y in 'ptr_rectangle'.

Parameters:
ptr_gfx | A pointer to the Graphics structure
ptr_rectangle | A pointer to the rectangle to be scrolled
dx | A horizontal scroll shift value
dy | A vertical scroll shift value
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t rectangle;
     init_module(&main_module);
     rectangle.x = 10;
     rectangle.y = 10;
     rectangle.h = 20;
     rectangle.w = 40;
     ...
     TGraph_fill_rect_Ex( main_module.m_gfx, &rectangle );
     DisplayGraphics_show( main_module.m_gfx );
     ...
     // Make some graphic operation
     ...
     Graphics_scroll( main_module.m_gfx, &rectangle, 10, 10 );
     DisplayGraphics_show( main_module.m_gfx );
     ...

void Graphics_set_bitmap ( | struct Graphics * ptr_gfx,
 | struct Bitmap * bmp )

Sets a bitmap 'bmp' as the destination for drawings.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
bmp | A pointer to the destination bitmap
Returns:
None
   #include <cybiko.h>
     ...
     struct Bitmap bitmap;
     struct Graphics vgfx;
     ...
     Graphics_ctor( &vgfx );
     // SCREEN_WIDTH and SCREEN_HEIGHT are described in the 'Defines' section.
     Bitmap_ctor_Ex2( &bitmap, SCREEN_WIDTH, SCREEN_HEIGHT, 2 );
     ...
     // Now all drawing operations in the 'vgfx' graphics context will be performed on the 'bitmap' object.
     Graphics_set_bitmap( &vgfx, &bitmap );
     ...
See also:
Graphics_get_bitmap.

void Graphics_set_bkcolor ( | struct Graphics * ptr_gfx,
 | color_t fc )

Sets the current background color by calling TGraph_set_bkcolor.

Parameters:
ptr_gfx | A pointer to a TGraph object
fc | A color_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Bitmap bmp;
     ...
     init_module( &main_module );
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     ...
     // Set draw mode to mode OR.
     Graphics_set_draw_mode( main_module.m_gfx, DM_OR );
     // Set transparent color to CLR_BLACK
     Graphics_set_bkcolor( main_module.m_gfx, CLR_BLACK );
     // Draw all pixels of the bitmap except pixels with CLR_BLACK color.
     Graphics_draw_bitmap( main_module.m_gfx, &bmp, 30, 40, BM_NORMAL );
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...
See also:
TGraph_set_bkcolor, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void Graphics_set_clip ( | struct Graphics * ptr_gfx,
 | int fx,
 | int fy,
 | int fw,
 | int fh )

Sets a clip region, defined by the coordinates stored in the fx, fy, fw, and fh parameters.

Parameters:
ptr_gfx | A pointer to a Graphics object
fx | x-coordinate of the upper-left corner of the area to be clipped
fy | y-coordinate of the upper-left corner of the area to be clipped
fw | Width of the area to be clipped
fh | Height of the area to be clipped
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_clip ( main_module.m_gfx, &clip_region );
     if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
          ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
           Graphics_set_clip( main_module.m_gfx, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT );
     ...
See also:
Graphics_set_clip_Ex, Graphics_get_clip.

void Graphics_set_clip_Ex ( | struct Graphics * ptr_gfx,
 | struct rect_t * ptr_rectangle )

Duplicates the Graphics_set_clip function.
The region coordinates are stored in a rect_t object.

Parameters:
ptr_gfx | A pointer to a TGraph object
ptr_rectangle | A pointer to a rect_t object. By this structure we can define the region coordinates
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     struct rect_t new_clip_reg;
     init_module( &main_module );
     ...
     new_clip_reg.x = 10;
     new_clip_reg.y = 10;
     new_clip_reg.h = 100;
     new_clip_reg.w = 100;
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
          ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
           TGraph_set_clip( main_module.m_gfx, &new_clip_reg );
     ...
See also:
Graphics_set_clip.

void Graphics_set_color ( | struct Graphics * ptr_gfx,
 | color_t fc )

Sets the current foreground color.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
fc | A color value
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     if ( Graphics_get_color( main_module.m_gfx ) != CLR_LTGRAY )
     Graphics_set_color( main_module.m_gfx, CLR_LTGRAY);
     ...
See also:
Graphics_get_color, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void Graphics_set_draw_mode ( | struct Graphics * ptr_gfx,
 | drawmode_t dm )

Sets the current draw mode.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
dm | A draw mode
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     if ( Graphics_get_draw_mode( main_module.m_gfx ) != DM_PUT )
     Graphics_set_draw_mode( main_module.m_gfx, DM_PUT);
     ...
See also:
Graphics_get_draw_mode, DM_PUT, DM_OR, DM_XOR.

void Graphics_set_font ( | struct Graphics * ptr_gfx,
 | struct Font * font )

Sets the current font.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
font | A pointer to the initialized Font object
Returns:
None
   #include <cybiko.h>
     ...
     int str_plen;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     ...
See also:
Graphics_get_font.

void Graphics_set_pixel ( | struct Graphics * ptr_gfx,
 | int fx,
 | int fy,
 | color_t fc )

The color, defined by the 'fc' parameter.
Sets the color of the pixel at coordinates ( fx , fy ).

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
fx | x-coordinate of the required pixel
fy | y-coordinate of the required pixel
fc | A color value
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     if ( Graphics_get_pixel( main_module.m_gfx, 10, 30 ) == CLR_BLACK )
          Graphics_set_pixel( main_module.m_gfx, 10, 30, CLR_WHITE );
     ...
See also:
Graphics_get_pixel, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

int Graphics_string_width ( | struct Graphics * ptr_gfx,
 | char * str )

Returns the width (in pixels) of a string 'str' for the current font.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
str | A pointer to the string
Returns:
The width (in pixels) of a string for the current font
   #include <cybiko.h>
     ...
     int str_plen;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     ...
     str_plen = Graphics_string_width( main_module.m_gfx, "Any string" );
     ...
See also:
Graphics_string_width_Ex.

int Graphics_string_width_Ex ( | struct Graphics * ptr_gfx,
 | char * str,
 | int len )

The extended version of the Graphics_string_width function.
Returns the width (in pixels) of the first 'len' symbols of a string 'str'.

Parameters:
ptr_gfx | A pointer to the initialized Graphics object
str | A pointer to the string
len | A maximum possible length of the drawn string
Returns:
The width (in pixels) of the first 'len' symbols of a string
   #include <cybiko.h>
     ...
     int str_plen;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     Graphics_set_font( main_module.m_gfx, cool_normal_font );
     ...
     str_plen = Graphics_string_width_Ex( main_module.m_gfx, "Any string", 20 );
     ...
See also:
Graphics_string_width.


rect_t Struct Reference

Public Methods
void | rect_set (struct rect_t *ptr_rect, int x, int y, int width, int height)
bool | rect_and (struct rect_t *ptr_rectangle, struct rect_t *ptr_rectangle_1, struct rect_t *ptr_rectangle_2)
bool | rect_or (struct rect_t *ptr_rectangle, struct rect_t *ptr_rectangle_1, struct rect_t *ptr_rectangle_2)

Public Attributes
short | x
short | y
short | w
short | h

Detailed Description

A rectangle.

See also:
Drawing Primitives and Screen Manipulation

Member Function Documentation

bool rect_and ( | struct rect_t * ptr_rectangle,
 | struct rect_t * ptr_rectangle_1,
 | struct rect_t * ptr_rectangle_2 )

Intersects two rectangles.
Sets the value ptr_rectangle into an intersection of two given rectangles.

Parameters:
ptr_rectangle | The intersection result
ptr_rectangle_1 | The first rectangle to intersect
ptr_rectangle_2 | The second rectangle to intersect
Returns:
TRUE if a valid rectangle intersection was obtained, or FALSE if no intersection was found
       #include <cybiko.h>
       #define VEHICLE_WIDTH          60
       #define VEHICLE_HEIGHT         20
       ...
       int x1;
       int x2;
       int y1;
       int y2;
       struct rect_t vehicle_1_boundary;
       struct rect_t vehicle_2_boundary;
       struct rect_t intersection;
       ...
       rect_set( &vehicle_1_boundary, x1, y1, VEHICLE_WIDTH, VEHICLE_HEIGHT );
       rect_set( &vehicle_2_boundary, x2, y2, VEHICLE_WIDTH, VEHICLE_HEIGHT );
       //  Checks collision of the vehicles.
       if( rect_and( &intersection, &vehicle_1_boundary, &vehicle_2_boundary ) )
       ...

bool rect_or ( | struct rect_t * ptr_rectangle,
 | struct rect_t * ptr_rectangle_1,
 | struct rect_t * ptr_rectangle_2 )

Merges two rectangles.
Sets the value ptr_rectangle into a union of two given rectangles.

Parameters:
ptr_rectangle | The merged result
ptr_rectangle_1 | The first rectangle to join
ptr_rectangle_2 | The second rectangle to join
Returns:
TRUE if a valid rectangle was obtained, or FALSE otherwise
       #include <cybiko.h>
       #define VEHICLE_WIDTH          60
       #define VEHICLE_HEIGHT         20
       ...
       int x1;
       int x2;
       int y1;
       int y2;
       struct rect_t vehicle_1_boundary;
       struct rect_t vehicle_2_boundary;
       struct rect_t common_boundary;
       ...
       rect_set( &vehicle_1_boundary, x1, y1, VEHICLE_WIDTH, VEHICLE_HEIGHT );
       rect_set( &vehicle_2_boundary, x2, y2, VEHICLE_WIDTH, VEHICLE_HEIGHT );
       rect_or( &common_boundary, &vehicle_1_boundary, &vehicle_2_boundary );
       ...

void rect_set ( | struct rect_t * ptr_rect,
 | int x,
 | int y,
 | int width,
 | int height )

Initializes a rectangle.

Parameters:
ptr_rect | A pointer to the rect_t structure
x | The rectangle's x-coordinate
y | The rectangle's y-coordinate
width | The rectangle's width
height | The rectangle's height
Returns:
None
       #include <cybiko.h>
       #define VEHICLE_WIDTH          60
       #define VEHICLE_HEIGHT         20
       ...
       int x1;
       int x2;
       int y1;
       int y2;
       struct rect_t vehicle_1_boundary;
       struct rect_t vehicle_2_boundary;
       struct rect_t intersection;
       ...
       rect_set( &vehicle_1_boundary, x1, y1, VEHICLE_WIDTH, VEHICLE_HEIGHT );
       rect_set( &vehicle_2_boundary, x2, y2, VEHICLE_WIDTH, VEHICLE_HEIGHT );
       //  Checks collision of the vehicles.
       if( rect_and( &intersection, &vehicle_1_boundary, &vehicle_2_boundary ) )
       ...

Member Data Documentation

short h

Rectangle's height.

short w

Rectangle's width.

short x

Rectangle's x-coordinate.

short y

Rectangle's y-coordinate.


TGraph Struct Reference

Inheritance diagram for TGraph

Public Methods
void | TGraph_draw_rect (struct TGraph *ptr_graph, int x, int y, int w, int h)
void | TGraph_draw_rect_Ex (struct TGraph *ptr_graph, struct rect_t *rc)
void | TGraph_fill_rect (struct TGraph *ptr_graph, int x, int y, int w, int h)
void | TGraph_fill_rect_Ex (struct TGraph *ptr_graph, struct rect_t *rc)
color_t | TGraph_get_color (struct TGraph *ptr_graph)
drawmode_t | TGraph_get_draw_mode (struct TGraph *ptr_graph)
void | TGraph_set_draw_mode (struct TGraph *ptr_graph, drawmode_t mode)
void | TGraph_draw_hline (struct TGraph *ptr_graph, int x, int y, int dx)
void | TGraph_draw_vline (struct TGraph *ptr_graph, int x, int y, int dy)
void | TGraph_draw_line (struct TGraph *ptr_graph, int x1, int y1, int x2, int y2)
void | TGraph_fill_screen (struct TGraph *ptr_graph, color_t fc)
void | TGraph_get_clip (struct TGraph *ptr_graph, struct rect_t *rc)
color_t | TGraph_get_pixel (struct TGraph *ptr_graph, int x, int y)
void | TGraph_put_background (struct TGraph *ptr_graph, char *ptr_background)
char* | TGraph_get_buf_addr (struct TGraph *ptr_graph)
int | TGraph_get_bytes_total (struct TGraph *ptr_graph)
void | TGraph_scroll (struct TGraph *ptr_graph, int left, int top, int width, int height, int dx, int dy)
void | TGraph_set_bkcolor (struct TGraph *ptr_graph, color_t color)
void | TGraph_set_clip (struct TGraph *ptr_graph, int x, int y, int width, int height)
void | TGraph_set_clip_Ex (struct TGraph *ptr_graph, struct rect_t *rc)
void | TGraph_set_color (struct TGraph *ptr_graph, color_t color)
void | TGraph_set_pixel (struct TGraph *ptr_graph, int x, int y, color_t color)

Detailed Description

The TGraph structure is implemented by raster and 2D-graphics. It is designated for working with graphic primitives like rectangles, lines and pixels. It functions similarly to many other SDK structures, in that you must use a TGraph constructor to create the TGraph object, and release it after use with a TGraph deconstructor.

The structure diagram below shows that TGraph is a parent structure for other structures such as Graphics and DisplayGraphics. This means that raster and 2D-graphics operations for Graphics and DisplayGraphics structures are implemented in their parent structure.

To use all TGraph functions you must obtain the Display Graphics Context from the init_module function. It has only one parameter, called the main application module parameter, and it must be obtained by the module_t structure.

See examples for related functions.

See also:
Drawing Primitives and Screen Manipulation

Member Function Documentation

void TGraph_draw_hline ( | struct TGraph * ptr_graph,
 | int x,
 | int y,
 | int dx )

Draws a horizontal line from point ( x , y ) to point ( dx , y ).

Parameters:
ptr_graph | A pointer to the graphics context
x | x-coordinate of the horizontal line's starting point
y | y-coordinate of the horizontal line's starting point
dx | x-coordinate of the horizontal line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
     if ( TGraph_get_color( main_module.m_gfx ) != CLR_LTGRAY )
        TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_draw_hline( main_module.m_gfx, 10, 10, 20);
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_draw_line, TGraph_draw_vline.

void TGraph_draw_line ( | struct TGraph * ptr_graph,
 | int x1,
 | int y1,
 | int x2,
 | int y2 )

Draws a solid line from point ( x1 , y1 ) to point ( x2 , y2 ).

Parameters:
ptr_graph | A pointer to the graphic context
x1 | x-coordinate of the line's starting point
y1 | y-coordinate of the line's starting point
x2 | x-coordinate of the line's finishing point
y2 | y-coordinate of the line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY or CLR_BLACK.
     if ( TGraph_get_color( main_module.m_gfx ) != CLR_LTGRAY )
        TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_draw_line( main_module.m_gfx, 10, 10, 20, 60 );
     ...
     // To send the current graphics page to the TGraph_draw_rect_Ex Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_draw_hline, TGraph_draw_vline.

void TGraph_draw_rect ( | struct TGraph * ptr_graph,
 | int x,
 | int y,
 | int w,
 | int h )

Draws a rectangular frame.

Parameters:
ptr_graph | A pointer to a TGraph object
x | The rectangle's left coordinate
y | The rectangle's top coordinate
w | The rectangle's width
h | The rectangle's height
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to Cybiko graphics context
      TGraph_draw_rect( main_module.m_gfx, 10, 10, 100, 100 );
     ...
     // To send the current graphics page to Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_draw_rect_Ex.

void TGraph_draw_rect_Ex ( | struct TGraph * ptr_graph,
 | struct rect_t * rc )

The extended version of the TGraph_draw_rect function.
Draws a rectangular frame using the info contained in a rect_t object.

Parameters:
ptr_graph | A pointer to a TGraph object
rc | A pointer to a tect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct rect_t rc;
     struct module_t main_module;
     init_module( &main_module );
     rc.top = rc.left = 10;
     rc.width = rc.height = 100;
     ...
     // main_module.m_gfx is a pointer to Cybiko graphics context
      TGraph_draw_rect_Ex( main_module.m_gfx, &rc );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_draw_rect.

void TGraph_draw_vline ( | struct TGraph * ptr_graph,
 | int x,
 | int y,
 | int dy )

Draws vertical line from point ( x , y ) to point ( x , dy ).

Parameters:
ptr_graph | A pointer to the graphic context
x | x-coordinate of the vertical line's starting point
y | y-coordinate of the vertical line's starting point
dy | y-coordinate of the vertical line's finishing point
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one from following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
     if ( TGraph_get_color( main_module.m_gfx ) != CLR_LTGRAY )
        TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_draw_vline( main_module.m_gfx, 10, 10, 20);
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_draw_line, TGraph_draw_hline.

void TGraph_fill_rect ( | struct TGraph * ptr_graph,
 | int x,
 | int y,
 | int w,
 | int h )

Fills a rectangle at the specified coordinates with the current color.

Parameters:
ptr_graph | A pointer to a TGraph object
x | The rectangle's left coordinate
y | The rectangle's top coordinate
w | The rectangle's width
h | The rectangle's height
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
      TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_fill_rect_Ex.

void TGraph_fill_rect_Ex ( | struct TGraph * ptr_graph,
 | struct rect_t * rc )

The extended version of the TGraph_fill_rect function.
Fills a rectangle at the specified coordinates with the current color.

Parameters:
ptr_graph | A pointer to a TGraph object
rc | A pointer to a tect_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct rect_t rc;
     struct module_t main_module;
     init_module( &main_module );
     rc.top = rc.left = 10;
     rc.width = rc.height = 100;
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
      TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_fill_rect_Ex( main_module.m_gfx, &rc );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_fill_rect.

void TGraph_fill_screen ( | struct TGraph * ptr_graph,
 | color_t fc )

Fills the screen with the color 'fc'.

Parameters:
ptr_graph | A pointer to a TGraph object
fc | The color value
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_fill_screen function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
     TGraph_fill_screen( main_module.m_gfx, CLR_BLACK );
     ...
     // To send the current graphisc page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_put_background, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

char * TGraph_get_buf_addr ( struct TGraph * ptr_graph )

Returns a pointer to an image of a TGraph object's destination.

Parameters:
ptr_graph A pointer to a TGraph object
Returns:
A pointer to an image of a TGraph object's destination

int TGraph_get_bytes_total ( struct TGraph * ptr_graph )

Returns the screen buffer size, in bytes.

Parameters:
ptr_graph A pointer to a TGraph object
Returns:
The screen bufzfer size in bytes
   #include <cybiko.h>
     ...
     struct module_t main_module;
     char*  ptr_display_buffer;
     init_module( &main_module );
     ...
     // Allocating memory for buffer
     ptr_display_buffer = (char* ) malloc( TGraph_get_bytes_total( main_module.m_gfx ) );
     ...
     // Make some graphics operation ( draw a picture, for instance)
     ...
     // Save the screen
     memcpy( ptr_display_buffer, DisplayGraphics_get_page_ptr(main_module.m_gfx, 0), TGraph_get_bytes_total(main_module.m_gfx));
     ...
     // Make another graphics operation
     ...
     // Restore the screen. Works very fast.
     TGraph_put_background( main_module.m_gfx, ptr_display_buffer );
     ...
     // Make another graphics operation
     ...
     // Restore the screen again.
     TGraph_put_background( main_module.m_gfx, ptr_display_buffer );
     ...
     free( ptr_display_buffer );

void TGraph_get_clip ( | struct TGraph * ptr_graph,
 | struct rect_t * rc )

Returns the clip region stored in the 'rc' object.

Parameters:
ptr_graph | A pointer to a TGraph object
rc | A pointer to a rect_t object
Returns:
None
   #include <cybiko.h>
       ...
       struct module_t main_module;
       struct rect_t clip_region;
       init_module( &main_module );
       ...
       // main_module.m_gfx is a pointer to the Cybiko graphics context.
       TGraph_get_clip ( main_module.m_gfx, &clip_region );
       if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
            ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
             TGraph_set_clip( main_module.m_gfx, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT );
       ...
See also:
TGraph_set_clip.

color_t TGraph_get_color ( struct TGraph * ptr_graph )

Returns a TGraph object's current color.

Parameters:
ptr_graph A pointer to a TGraph object
Returns:
The TGraph object's current color
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
     if ( TGraph_get_color( main_module.m_gfx ) != CLR_LTGRAY )
        TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_set_color, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

drawmode_t TGraph_get_draw_mode ( struct TGraph * ptr_graph )

Returns the current draw mode of a TGraph object.

Parameters:
ptr_graph A pointer to a TGraph object
Returns:
The current draw mode of a TGraph object
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     ...
     // The second parameter in the TGraph_set_draw_mode function is the draw mode value.
     // This value must be one of the following: DM_XOR, DM_OR, or DM_PUT.
     if ( TGraph_get_draw_mode( main_module.m_gfx ) != DM_PUT )
        TGraph_set_draw_mode( main_module.m_gfx, DM_PUT );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_set_draw_mode, DM_XOR, DM_OR, DM_PUT.

color_t TGraph_get_pixel ( | struct TGraph * ptr_graph,
 | int x,
 | int y )

Returns the color of the pixel at coordinate ( x , y ).

Parameters:
ptr_graph | A pointer to a TGraph object
x | x-coordinate of the required pixel
y | y-coordinate of the required pixel
Returns:
The color of the pixel at coordinate ( x , y )
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( TGraph_get_pixel( main_module.m_gfx, 10, 30 ) == CLR_BLACK )
          TGraph_set_pixel( main_module.m_gfx, 10, 30, CLR_WHITE )
     ...
See also:
TGraph_set_pixel, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void TGraph_put_background ( | struct TGraph * ptr_graph,
 | char * ptr_background )

Sets an image pointed by ptr_background as a background image.

Parameters:
ptr_graph | A pointer to a TGraph object
ptr_background | A pointer to a background image
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     char*  ptr_display_buffer;
     init_module( &main_module );
     ...
     // Allocating memory for buffer
     ptr_display_buffer = (char* ) malloc( TGraph_get_bytes_total( main_module.m_gfx ) );
     ...
     // Make some graphics operation ( draw a picture, for instance)
     ...
     // Save the screen
     memcpy( ptr_display_buffer, DisplayGraphics_get_page_ptr(main_module.m_gfx, 0), TGraph_get_bytes_total(main_module.m_gfx));
     ...
     // Make another graphics operation
     ...
     // Restore the screen. Works very fast.
     TGraph_put_background( main_module.m_gfx, ptr_display_buffer );
     ...
     // Make another graphics operation
     ...
     // Restore the screen again.
     TGraph_put_background( main_module.m_gfx, ptr_display_buffer );
     ...
     free( ptr_display_buffer );
See also:
TGraph_fill_screen.

void TGraph_scroll ( | struct TGraph * ptr_graph,
 | int left,
 | int top,
 | int width,
 | int height,
 | int dx,
 | int dy )

Scrolls the rectangle defined by ( x, y, width, height ) parameters.
The scroll values are dx and dy.

Parameters:
ptr_graph | A pointer to a TGraph object
left | x-coordinate of the rectangle to be scrolled
top | y-coordinate of the rectangle to be srolled
width | A width of the rectangle to be scrolled
height | A height of the rectangle to be scrolled
dx | A horizontal shift value
dy | A vertical shift value
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t  rectangle;
     init_module(&main_module);
     rectangle.x = 10;
     rectangle.y = 10;
     rectangle.h = 20;
     rectangle.w = 40;
     ...
     TGraph_fill_rect_Ex( main_module.m_gfx, &rectangle );
     DisplayGraphics_show( main_module.m_gfx );
     ...
     // Make some graphics operation
     ...
     TGraph_scroll( main_module.m_gfx, &rectangle, 10, 10 );
     DisplayGraphics_show( main_module.m_gfx );
     ...

void TGraph_set_bkcolor ( | struct TGraph * ptr_graph,
 | color_t color )

Sets the transparent color as the color defined in the 'color' parameter.

Parameters:
ptr_graph | A pointer to a TGraph object
color | A color value
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct Bitmap bmp;
     ...
     init_module( &main_module );
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     ...
     // Set draw mode to mode OR.
     TGraph_set_draw_mode( main_module.m_gfx, DM_OR );
     // Set transparent color to CLR_BLACK
     TGraph_set_bkcolor( main_module.m_gfx, CLR_BLACK );
     // Draw all pixels of the bitmap except pixels with CLR_BLACK color.
     Graphics_draw_bitmap( main_module.m_gfx, &bmp, 30, 40, BM_NORMAL );
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...
See also:
TGraph_set_color, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

void TGraph_set_clip ( | struct TGraph * ptr_graph,
 | int x,
 | int y,
 | int width,
 | int height )

Sets the clipping region.

Parameters:
ptr_graph | A pointer to a TGraph object
x | x-coordinate of the clipping region
y | y-coordinate of the clipping region
width | A width of the clipping region
height | A height of the clipping region
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
          ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
           TGraph_set_clip( main_module.m_gfx, 0, 0, SCREEN_WIDTH, SCREEN_HEIGHT );
     ...
See also:
TGraph_set_clip_Ex.

void TGraph_set_clip_Ex ( | struct TGraph * ptr_graph,
 | struct rect_t * rc )

Sets the clipping region.
This is an extended version of the TGraph_set_clip function.

Parameters:
ptr_graph | A pointer to a TGraph object
rc | A pointer to a rect_t object. By this structure we can define the region coordinates
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     struct rect_t new_clip_reg;
     init_module( &main_module );
     ...
     new_clip_reg.x = 10;
     new_clip_reg.y = 10;
     new_clip_reg.h = 100;
     new_clip_reg.w = 100;
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( (clip_region.x != 0) || ( clip_region.y != 0) ||
          ( clip_region.w != SCREEN_WIDTH) ||( clip_region.h != SCREEN_HEIGHT)) )
           TGraph_set_clip( main_module.m_gfx, &new_clip_reg );
     ...
See also:
TGraph_set_clip.

void TGraph_set_color ( | struct TGraph * ptr_graph,
 | color_t color )

Sets the foreground color.

Parameters:
ptr_graph | A pointer to a TGraph object
color | A pointer to a color_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
     if ( TGraph_get_color( main_module.m_gfx ) != CLR_LTGRAY )
        TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     TGraph_draw_line( main_module.m_gfx, 10, 10, 20, 60 );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_set_bkcolor, TGraph_get_color, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.

void TGraph_set_draw_mode ( | struct TGraph * ptr_graph,
 | drawmode_t mode )

Sets the current draw mode of a TGraph object.

Parameters:
ptr_graph | A pointer to a TGraph structure
mode | A drawmode_t object
Returns:
None
   #include "cybiko.h"
     ...
     struct module_t main_module;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     // The second parameter in the TGraph_set_color function is the color value.
     // This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK.
     TGraph_set_color( main_module.m_gfx, CLR_LTGRAY );
     ...
     // The second parameter in the TGraph_set_draw_mode function is the draw mode value.
     // This value must be one of the following: DM_XOR, DM_OR, or DM_PUT.
     if ( TGraph_get_draw_mode( main_module.m_gfx ) != DM_PUT )
        TGraph_set_draw_mode( main_module.m_gfx, DM_PUT );
     TGraph_fill_rect( main_module.m_gfx, 5, 5, 30, 30 );
     ...
     // To send the current graphics page to the Cybiko display you should use this function
     DisplayGraphics_show( main_module.m_gfx );
See also:
TGraph_get_draw_mode, DM_XOR, DM_OR, DM_PUT.

void TGraph_set_pixel ( | struct TGraph * ptr_graph,
 | int x,
 | int y,
 | color_t color )

Sets the color for the pixel at the coordinates ( x, y ).

Parameters:
ptr_graph | A pointer to a TGraph object
x | x-coordinate of the required pixel
y | y-coordinate of the required pixel
color | A pointer to a color_t object
Returns:
None
   #include <cybiko.h>
     ...
     struct module_t main_module;
     struct rect_t clip_region;
     init_module( &main_module );
     ...
     // main_module.m_gfx is a pointer to the Cybiko graphics context.
     TGraph_get_clip ( main_module.m_gfx, &clip_region );
     if ( TGraph_get_pixel( main_module.m_gfx, 10, 30 ) == CLR_BLACK )
          TGraph_set_pixel( main_module.m_gfx, 10, 30, CLR_WHITE )
     ...
See also:
TGraph_get_pixel, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.


Bitmaps and Bitmap Sequences

Defines
#define | BM_NORMAL 0
#define | BM_INVERSE 1
#define | BM_FLIP_X 2
#define | BM_FLIP_Y 4

Functions
void | draw_lib (int lib_index, int frame, int x, int y, short mode)

Compounds
struct | Bitmap | A structure for creating and working with simple bitmapped objects
struct | BitmapSequence | While the Bitmap structure is used for working with a single bitmap, the BitmapSequence is used for working with a Bitmap array

Detailed Description

The Bitmap structure is used for work with a single bitmap, while the BitmapSequence is used for work with a Bitmap array. (see Bitmap and BitmapSequence).

Define Documentation

#define BM_FLIP_X 2

Invert x coordinate.

#define BM_FLIP_Y 4

Invert y coordinate.

#define BM_INVERSE 1

Invert colors.
Obsolete (no longer supported)

#define BM_NORMAL 0

Keep as is.

Function Documentation

void draw_lib ( | int lib_index,
 | int frame,
 | int x,
 | int y,
 | short mode )

Draws a bitmap in the specified position.

Parameters:
lib_index | is the index of a *.pic file in the "filer.exe" file list (the first element has a 0 index)
frame | is the index of a bitmap frame in a *.pic file (the first frame has a 0 index)
x | is the x-coordinate of a bitmap
y | is the y-coordinate of a bitmap
mode | must be one of the following: BM_NORMAL, BM_INVERSE, BM_FLIP_X, BM_FLIP_Y
Returns:
None
   #include <cybiko.h>
     ...
     // This code is from makefile for test.app
     // test.app : tmp/bytecode.bin
     //            filer.exe a test.app res/font.pic tmp/bytecode.bin $(SDK)/lib/main.e
     draw_lib( 0, 0, 10, 10, BM_NORMAL );
     // The first bitmap from the "font.pic" bitmaps sequence would be draw.
     ...
See also:
BM_NORMAL, BM_INVERSE, BM_FLIP_X, BM_FLIP_Y.


Bitmap Struct Reference

Public Methods
struct Bitmap* | Bitmap_ctor (struct Bitmap *ptr_bitmap)
struct Bitmap* | Bitmap_ctor_Ex1 (struct Bitmap *ptr_bitmap, char *filename)
struct Bitmap* | Bitmap_ctor_Ex2 (struct Bitmap *ptr_bitmap, int width, int height, int bpp)
struct Bitmap* | Bitmap_ctor_Ex3 (struct Bitmap *ptr_bitmap, struct Bitmap *templ)
void | Bitmap_dtor (struct Bitmap *ptr_bitmap, int memory_flag)
void | Bitmap_fill (struct Bitmap *ptr_bitmap, color_t color)
void | Bitmap_clear (struct Bitmap *ptr_bitmap)
bool | Bitmap_load (struct Bitmap *ptr_bitmap, struct Input *input)
bool | Bitmap_store (struct Bitmap *ptr_bitmap, struct Output *output)
int | Bitmap_get_w (struct Bitmap *ptr_bitmap)
int | Bitmap_get_h (struct Bitmap *ptr_bitmap)

Public Attributes
int | w
int | h

Detailed Description

A structure for creating and working with simple bitmap object. Using this structure, you can create a bitmap object in one of four ways:

  1. Create an empty bitmap object the same way Bitmap_ctor does;
  2. Create a Bitmap object using a resource;
  3. Create an empty bitmap with memory allocated for it;
  4. Create a Bitmap object that is an exact copy of an another bitmap.
Make sure to create every Bitmap object using one of the "constructor" functions, and to release each Bitmap object with the Bitmap_dtor function.

Use the Bitmap_fill function to fill a bitmap with the color marked by the second function parameter's pointer. The second parameter also specifies the type color, via the color_t type function. This function is defined in the header, and described in the "Typedefs" section. * a header and described in the "Typedefs" section. You can implement operations with streams using the Bitmap_load and Bitmap_storefunctions.

Please study the examples for these functions carefully.
See also:
Bitmaps and Bitmap Sequences

Member Function Documentation

void Bitmap_clear ( struct Bitmap * ptr_bitmap )

Fills whole bitmap by white color.

Parameters:
ptr_bitmap A pointer to the initialized Bitmap object
Returns:
None
   #include <cybiko.h>
     ...
     struct Bitmap bitmap;
     ...
     Bitmap_fill( &bitmap, CLR_DKGRAY );
     ...
     // It is the same as Bitmap_fill( ptr_bitmap, CLR_WHITE );
     Bitmap_clear( &bitmap );
     ...
     Bitmap_dtor( &bitmap, LEAVE_MEMORY );
See also:
Bitmap_fill.

struct Bitmap * Bitmap_ctor ( struct Bitmap * ptr_bitmap )

The simple Bitmap constructor.
Creates an empty bitmap. First you must create a Bitmap object and transfer the pointer on it into this function.

Parameters:
ptr_bitmap A pointer to the Bitmap structure
Returns:
A pointer to an initialized Bitmap object
   #include <cybiko.h>
     ...
     struct Bitmap bitmap;
     Bitmap_ctor( &bitmap );
     ...
     Bitmap_dtor( &bitmap, LEAVE_MEMORY );

struct Bitmap * Bitmap_ctor_Ex1 ( | struct Bitmap * ptr_bitmap,
 | char * filename )

The first extended version of the Bitmap_ctor function.
It creates an empty bitmap from a resource file.

Parameters:
ptr_bitmap | A pointer to the Bitmap structure
filename | The name of a resource file
Returns:
A pointer to an initialized Bitmap object
   #include <cybiko.h>
     ...
     struct Bitmap bmp;
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
See also:
Bitmap_ctor

struct Bitmap * Bitmap_ctor_Ex2 ( | struct Bitmap * ptr_bitmap,
 | int width,
 | int height,
 | int bpp )

The second extended version of the Bitmap_ctor function.
It creates an empty bitmap and allocates memory for it.

Parameters:
ptr_bitmap | A pointer to the Bitmap structure
width | The width of the bitmap object
height | The height of the bitmap object
bpp | The number of bits per pixel that you need to allocate - 2 bits for a four color display, and 1 bit for a monochrome display
Returns:
A pointer to an initialized Bitmap object
   #include <cybiko.h>
     ...
     struct Bitmap bmp;
     // SCREEN_WIDTH and SCREEN_HEIGHT are described in the 'Defines' section.
     Bitmap_ctor_Ex2( &bmp, SCREEN_WIDTH, SCREEN_HEIGHT, 2 );
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
See also:
Bitmap_ctor

struct Bitmap * Bitmap_ctor_Ex3 ( | struct Bitmap * ptr_bitmap,
 | struct Bitmap * templ )

The third extended version of the Bitmap_ctor function.
Builds the exact copy of another bitmap.

Parameters:
ptr_bitmap | A pointer to destination Bitmap object
templ | A pointer to template Bitmap object
Returns:
A pointer to initialized Bitmap object
   #include <cybiko.h>
     ...
     struct Bitmap  bitmap_templ;
     Bitmap_ctor_Ex1( &bitmap_templ, "bmp.pic" );
     ...
     // Working with the 'ptr_bitmap_templ' bitmap.
     ...
     struct Bitmap  bitmap;
     Bitmap_ctor_Ex3( &bitmap, &bitmap_templ );
     ...
     Bitmap_dtor( &bitmap, LEAVE_MEMORY );
     Bitmap_dtor( &bitmap_templ, LEAVE_MEMORY );
See also:
Bitmap_ctor

void Bitmap_dtor ( | struct Bitmap * ptr_bitmap,
 | int memory_flag )

Destructor.
This function deletes a Bitmap object.

Parameters:
ptr_bitmap | A pointer to the initialized Bitmap object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If memory_flag is FREE_MEMORY when destructor frees memory, allocated for the object. FREE_MEMORY used if memory was allocated by malloc(). If object was static or allocated in stack use LEAVE_MEMORY
Returns:
None
   #include <cybiko.h>
     ...
     struct Bitmap bitmap;
     // SCREEN_WIDTH and SCREEN_HEIGHT are defined in the "cyber-graph.h" file.
     Bitmap_ctor_Ex2( &bitmap, SCREEN_WIDTH, SCREEN_HEIGHT, 2 );
     ...
     Bitmap_dtor( &bitmap, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

void Bitmap_fill ( | struct Bitmap * ptr_bitmap,
 | color_t color )

Fills whole bitmap by a color pointed on the color_t value.
The color_t type is described in the 'Typedefs' section.

Parameters:
ptr_bitmap | A pointer to the initialized Bitmap object
color | The color_t value. This value must be one of the following: CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, or CLR_BLACK
Returns:
None
   #include <cybiko.h>
     ...
     struct Bitmap bitmap;
     ...
     Bitmap_fill( &bitmap, CLR_BLACK );
     ...
     Bitmap_dtor( &bitmap, LEAVE_MEMORY );
See also:
Bitmap_clear, CLR_WHITE, CLR_LTGRAY, CLR_DKGRAY, CLR_BLACK.

int Bitmap_get_h ( struct Bitmap * ptr_bitmap )

Returns physical height of the Bitmap (in pixels).

Parameters:
ptr_bitmap A pointer to the BitmapSequence structure
Returns:
A physical height of the Bitmap (in pixels)
   #include <cybiko.h>
     ...
     struct Bitmap gfx_bmp;
     int height_gfx, width_gfx;
     ...
     // Returns physical height of the Bitmap object
     height_gfx = Bitmap_get_h( &gfx_bmp );
     // Returns physical width of the Bitmap object
     width_gfx = Bitmap_get_w( &gfx_bmp );
     ...
See also:
Bitmap_get_w.

int Bitmap_get_w ( struct Bitmap * ptr_bitmap )

Returns physical width of the Bitmap (in pixels).

Parameters:
ptr_bitmap A pointer to the BitmapSequence structure
Returns:
A physical width of the Bitmap (in pixels)
   #include <cybiko.h>
     ...
     struct Bitmap gfx_bmp;
     int height_gfx, width_gfx;
     ...
     // Returns physical height of the Bitmap object
     height_gfx = Bitmap_get_h( &gfx_bmp );
     // Returns physical width of the Bitmap object
     width_gfx = Bitmap_get_w( &gfx_bmp );
     ...
See also:
Bitmap_get_h.

bool Bitmap_load ( | struct Bitmap * ptr_bitmap,
 | struct Input * input )

Loads bitmap from an opened stream.

Parameters:
ptr_bitmap | A pointer to the initialized Bitmap object
input | A pointer to Input stream
Returns:
TRUE if a bitmap object was loaded successfully
   #include <cybiko.h>
     ...
     struct Input * ptr_input;
     struct Bitmap  bmp;
     ...
     Bitmap_ctor(&bmp);
     ...
     // Your make file must have the archive resource "bmp.pic" linked by filer.exe.
     // For example, see the Cybiko Compiler's Introduction Section
     ptr_input = open_resource_Ex( "bmp.pic" );
     if( !Bitmap_load( &bmp, ptr_input ) )
         return FALSE;
     else
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     Input_dtor( ptr_input, LEAVE_MEMORY );
See also:
Bitmap_store.

bool Bitmap_store ( | struct Bitmap * ptr_bitmap,
 | struct Output * output )

Stores bitmap to an opened stream.

Parameters:
ptr_bitmap | A pointer to the initialized Bitmap object
output | A pointer to Output stream
Returns:
TRUE if a bitmap object was stored successfully
   #include <cybiko.h>
     ...
     struct Output * ptr_output;
     bool   fBmp_store;
     struct Bitmap bmp;
     struct module_t main_module;
     ...
     init_module( &main_module ); // Application module initialization
     ...
     Bitmap_ctor_Ex2( &bmp, SCREEN_WIDTH, SCREEN_HEIGHT, 2 );
     ...
     // Your make file must have the archive resource "bmp.pic" linked by filer.exe.
     // For example, see the Cybiko Compiler's Introduction Section.
     ptr_output = Archive_open_write_Ex( main_module.m_process->module->archive, "bmp.pic" );
     fBmp_store = Bitmap_store( &bmp, ptr_output );
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     Output_dtor( ptr_output, FREE_MEMORY );
See also:
Bitmap_load.

Member Data Documentation

int h

Establishes a physical bitmap height (in pixels).

int w

Establishes a physical bitmap width (in pixels).


BitmapSequence Struct Reference

Inheritance diagram for BitmapSequence

Public Methods
struct BitmapSequence* | BitmapSequence_ctor (struct BitmapSequence *ptr_bitmap_sequence)
struct BitmapSequence* | BitmapSequence_ctor_Ex (struct BitmapSequence *ptr_bitmap_sequence, char *file_name)
void | BitmapSequence_dtor (struct BitmapSequence *ptr_bitmap_sequence, int memory_flag)
int | BitmapSequence_get_size (struct BitmapSequence *ptr_bitmap_sequence)
struct Bitmap* | BitmapSequence_get_bitmap (struct BitmapSequence *ptr_bitmap_sequence, int bitmap_index)
bool | BitmapSequence_load (struct BitmapSequence *ptr_bitmap_sequence, struct Input *input)
bool | BitmapSequence_store (struct BitmapSequence *ptr_bitmap_sequence, struct Output *output)

Detailed Description

While the Bitmap structure above is used for working with a single bitmapped image, the BitmapSequence is used for working with a Bitmap array. To create a BitmapSequence object, you must use the BitmapSequence_ctor function.

Use the BitmapSequence_dtor function to release the created object by after you work with it. To receive the bitmap object from the bitmap sequence, use the BitmapSequence_get_bitmap function.

The BitmapSequence get size function determines the number of bitmap objects in the BitmapSequence object you can receive. Bitmap structure operations with streams are designated the same way. They are implemented in the BitmapSequence_load and BitmapSequence_store functions.

Please pay special attention to the examples for these functions.

See also:
Bitmaps and Bitmap Sequences

Member Function Documentation

struct BitmapSequence * BitmapSequence_ctor ( struct BitmapSequence * ptr_bitmap_sequence )

Simple BitmapSequence constructor.
Creates an empty bitmap sequence.

Parameters:
ptr_bitmap_sequence A pointer to the BitmapSequence structure
Returns:
A pointer to the initialized BitmapSequence object
   #include <cybiko.h>
     ...
     struct BitmapSequence bmps;
     BitmapSequence_ctor( &bmps );
     ...
     BitmapSequence_dtor( &bmps, LEAVE_MEMORY );
See also:
BitmapSequence_ctor_Ex.

struct BitmapSequence * BitmapSequence_ctor_Ex ( | struct BitmapSequence * ptr_bitmap_sequence,
 | char * file_name )

This is the extended version of the BitmapSequence_ctor function.
It allows you to use a resource for creating a BitmapSequence object.

Parameters:
ptr_bitmap_sequence | A pointer to the BitmapSequence structure
file_name | A name of file, where BitmapSequense's data were stored
Returns:
A pointer to the initialized BitmapSequence object
   #include <cybiko.h>
     ...
     struct BitmapSequence bmps;
     BitmapSequence_ctor_Ex( &bmps, "MyFont.pic" );
     ...
     BitmapSequence_dtor( &bmps, LEAVE_MEMORY );
See also:
BitmapSequence_ctor.

void BitmapSequence_dtor ( | struct BitmapSequence * ptr_bitmap_sequence,
 | int memory_flag )

Destructor.
This function deletes the BitmapSequence object.

Parameters:
ptr_bitmap_sequence | A pointer to the initialized BitmapSequence object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. If the object was static or allocated in stack
Returns:
None
   #include <cybiko.h>
     ...
     struct BitmapSequence bmps;
     BitmapSequence_ctor_Ex( &bmps, "MyFont.pic" );
     ...
     BitmapSequence_dtor( &bmps, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct Bitmap * BitmapSequence_get_bitmap ( | struct BitmapSequence * ptr_bitmap_sequence,
 | int bitmap_index )

Returns a pointer on the Bitmap object that has the 'bitmap_index' index.

Parameters:
ptr_bitmap_sequence | A pointer to the BitmapSequence object
bitmap_index | The bitmap index in the BitmapSequence structure
Returns:
A pointer to the Bitmap object that has the 'bitmap_index' index
   #include <cybiko.h>
     ...
     struct BitmapSequence bmps;
     struct Bitmap * ptr_bmp_symbol_A;
     BitmapSequence_ctor_Ex( &bmps , "font_1.pic" );
     ...
     ptr_bmp_symbol_A = BitmapSequence_get_bitmap( &bmps, 0 );
     BitmapSequence_dtor( &bmps, LEAVE_MEMORY );

int BitmapSequence_get_size ( struct BitmapSequence * ptr_bitmap_sequence )

Returns the number of bitmaps in a BitmapSequence object.

Parameters:
ptr_bitmap_sequence A pointer to the initialized BitmapSequence object
Returns:
The number of bitmaps in the BitmapSequence object
   #include <cybiko.h>
     ...
     struct BitmapSequence bmps;
     BitmapSequence_ctor_Ex( &bmps, "MyFont.pic" );
     ...
     TRACE( "%d symbols in this font", BitmapSequence_get_size( &bmps ) );
     ...
     BitmapSequence_dtor( &bmps, LEAVE_MEMORY );

bool BitmapSequence_load ( | struct BitmapSequence * ptr_bitmap_sequence,
 | struct Input * input )

Loads the bitmap sequence from an opened stream.

Parameters:
ptr_bitmap_sequence | A pointer to the BitmapSequence object
input | A pointer to the Input stream
Returns:
TRUE if bitmap sequence was loaded successfully
   #include <cybiko.h>
     ...
     struct Input * ptr_input;
     struct BitmapSequence bmps;
     ...
     // Your make file must have the archive resource "bmp.pic" linked by filer.exe.
     // For an example, see the Cybiko Compiler's Introduction Section.
     ptr_input = open_resource_Ex( "font_1.pic" );
     ...
     if( !BitmapSequence_load( &bmps, ptr_input ) )
     {
        ...
     }
     ...
     BitmapSequence_dtor( &bmps, LEAVE_MEMORY );
     Input_dtor( ptr_input, FREE_MEMORY );
See also:
BitmapSequence_store.

bool BitmapSequence_store ( | struct BitmapSequence * ptr_bitmap_sequence,
 | struct Output * output )

Stores a bitmap sequence to an opened stream.

Parameters:
ptr_bitmap_sequence | A pointer to the BitmapSequence object
output | A pointer to the Output stream
Returns:
TRUE if the bitmap sequence was stored successfully
   #include <cybiko.h>
     ...
     struct Output * ptr_output;
     bool fBmp_store;
     struct BitmapSequence bmps;
     struct module_t main_module;
     ...
     init_module( &main_module ); // Application module initialization
     ...
     Bitmap_ctor_Ex2( &bmp, SCREEN_WIDTH, SCREEN_HEIGHT, 2 );
     ...
     // Your make file must have the archive resource "bmp.pic" linked by filer.exe.
     // For an example, see the Cybiko Compiler's Introduction Section.
     ptr_output = Archive_open_write_Ex( main_module.m_process->module->archive, "font_1.pic" );
     fBmp_store = BitmapSequence_store( &bmps, ptr_output );
     ...
     BitmapSequence_dtor( &bmps, LEAVE_MEMORY );
     Output_dtor( ptr_output, FREE_MEMORY );
See also:
BitmapSequence_load.


3D Graphics

Typedefs
typedef short | fixed_t

Functions
void | cy3d_draw_background (char *buff, color_t sky_clr, color_t floor_clr)
void | cy3d_draw_sky (char *buff, color_t clr)
void | cy3d_draw_map_buffer (char *dst, char *src)
void | cy3d_draw_map_buffer_xor (char *dst, char *src)
void | cy3d_mirror_buffer (char *buff)
void | cy3d_draw_tex_column (char *buff, int ray, fixed_t y, raster_t *tex, int index, int column, int shift, int *zbuff)
void | cy3d_draw_sprite (char *buff, point_t p, raster_t *spr, int index, int *zbuff)
void | cy3d_draw_wall (char *buff, point_t p1, point_t p2, raster_t *tex, int index, int shift, int *zbuff)
raster_t* | cy3d_load (char *name)
raster_t* | cy3d_load_tex (int index)
raster_t* | cy3d_load_spr (int index)
fixed_t | cy3d_sin (int direction)
fixed_t | cy3d_cos (int direction)
int | cy3d_sqrt (long value)
point_t | cy3d_warp (point_t p, point_t camera, int direction)
point_t | cy3d_move (point_t p, fixed_t distance, int direction)
pos_t | cy3d_pos (point_t p)
point_t | cy3d_point (pos_t p)
fixed_t | cy3d_distance (point_t p1, point_t p2)
long | cy3d_distance2 (point_t p1, point_t p2)

Compounds
struct | point_t | A point on a plane, with the coordinates represented by fixed point (8.8) values
struct | pos_t | A point on a plane, with the coordinates represented by integer values
struct | raster_t | A collection of sprites or textures used by the CyOS 3D library

Detailed Description

These functions implement Wolfenstein3D/Ultima Underworld style graphics -- they simplify creation of your own 3D worlds. Please, pay special attention to the cy3d_draw_sprite() and cy3d_draw_wall() functions.

Typedef Documentation

typedef short fixed_t

Values with the fixed point ( 8.8 ).

Values with the fixed point ( 8.8 ). The 8 high bits represent the integer. The 8 low bits represent a fraction. (i.e. 0x0F80 is 15.5).

Function Documentation

fixed_t cy3d_cos ( int direction )

Calculates the cosine of the angle.

Parameters:
direction Value of the angle (in degrees). Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
Cosine of the angle
See also:
cy3d_sin.

fixed_t cy3d_distance ( | point_t p1,
 | point_t p2 )

Retrieves the distance between two points.

Parameters:
p1 | Position of the first point
p2 | Position of the second point Note: cy3d.dl must be loaded to the Cybiko computer
Returns:
the distance between two points.
See also:
cy3d_distance2.

long cy3d_distance2 ( | point_t p1,
 | point_t p2 )

Retrieves the square of the distance between the two points.

Parameters:
p1 | Position of the first point.
p2 | Position of the second point. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
Square of the distance between the two points
   #include <cywin.h>
   ...
   long lSDistance;
   point_t first_location;
   point_t second_location;
   ...
   //Retrieves the square of the distance between the two points.
   lSDistance = cy3d_distance2( first_location, second_location );
   ...
See also:
cy3d_distance.

void cy3d_draw_background ( | char * buff,
 | color_t sky_clr,
 | color_t floor_clr )

Fills the top and bottom of the screen with the specified colors.

Parameters:
buff | Pointer to the video buffer.
sky_clr | Color of the top of the screen
floor_clr | Color of the bottom of the screen. Note: cy3d.dl must be loaded on the Cybiko computer.
Returns:
None

void cy3d_draw_map_buffer ( | char * dst,
 | char * src )

Copies from the source video buffer to the destination video buffer performing bitwise OR.

Parameters:
dst | Pointer to the destination video buffer.
src | Pointer to the source video buffer. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
None

void cy3d_draw_map_buffer_xor ( | char * dst,
 | char * src )

Copies from the source video buffer to the destination video buffer performing bitwise XOR.

Parameters:
dst | Pointer to the destination video buffer.
src | Pointer to the source video buffer. Note: cy3d.dl must be loaded on the Cybiko computer.
Returns:
None.

void cy3d_draw_sky ( | char * buff,
 | color_t clr )

Fills the top part of the screen with the specified color.

Parameters:
buff | Pointer to the video buffer
clr | Color of the screen top Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
None
   #include <cywin.h>
   ...
   struct module_t main_module;
   ...
   init_module( &main_module );
   ...
   char* ptr_video_page =
     DisplayGraphics_get_page_ptr( main_module.m_gfx, 0 );
   ...
   cy3d_draw_sky( ptr_video_page, CLR_LTGRAY );
   ...

void cy3d_draw_sprite ( | char * buff,
 | point_t p,
 | raster_t * spr,
 | int index,
 | int * zbuff )

Draws a sprite in the specified position in the 3D world.
Parts of the image that are not visible will be truncated (due to the z-buffer).

Parameters:
buff | Pointer to the video buffer
p | Position of the sprite in the 3D world
spr | Pointer to the collection of the sprites
index | The sprite's index in the sprite collection
zbuff | Pointer to the z-buffer. Note: cy3d.dl must be loaded on the Cybiko computer.
Returns:
None
   #include <cywin.h>
   ...
   // Coordinates of the Cybiko sign (sprite) in the scene.
   point_t sign_location[ 2 ] =
   {
     { 0, 512 }, { 0, -512 }
   };
   ...
   void render_objects( char* ptr_gfx_buffer,
     point_t camera, int direction, int* z_buffer )
   {
    int index;
    ...
    // Transforms and renders column.
    for( index = 0; index < MAX_COLUMN; index++ )
    {
      cy3d_draw_sprite( ptr_gfx_buffer,
        cy3d_warp( column_location[ index ], camera, direction ),
          ptr_column, 0, z_buffer );
    }
    // Transforms and renders signs.
    for( index = 0; index < MAX_SIGN; index++ )
    {
      int effective_index = ( camera.p_y > 0 ) ? 1 - index : index ;
      ...
      cy3d_draw_sprite( ptr_gfx_buffer,
        cy3d_warp( sign_location[ effective_index ], camera, direction ),
          ptr_sign, sign_frame, z_buffer );
    }
     sign_frame++;
     sign_frame %= 19;
   }
   ...
See also:
cy3d_draw_wall.

void cy3d_draw_tex_column ( | char * buff,
 | int ray,
 | fixed_t y,
 | raster_t * tex,
 | int index,
 | int column,
 | int shift,
 | int * zbuff )

Draws a column of the texture.
This is useful for rendering the walls in the 3D world. The corresponding element of the z-buffer will be updated.

Parameters:
buff | Pointer to the video buffer
ray | Index ( 0 - 159 ). tg( angle ) = ( 80 - ray ) / 100
y | y-coordinate of the column in the 3D world
tex | Pointer to the texture collection
index | Texture's index in the collection
column | Column's index in the texture ( 0 - 31 )
shift | Shifts the texture to vertical
zbuff | Pointer to the z-buffer. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
None

void cy3d_draw_wall ( | char * buff,
 | point_t p1,
 | point_t p2,
 | raster_t * tex,
 | int index,
 | int shift,
 | int * zbuff )

Draws wall in the 3D world.

Parameters:
pointer | To the video buffer
p1 | Starting point of the of the wall in the 3D world
p2 | Ending point of the of the wall in the 3D world
tex | Pointer to the texture collection
index | Texture's index in the collection
shift | Shifts the texture to vertical
zbuff | Pointer to the z-buffer. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
None
   #include <cywin.h>
   ...
   int iIndex, iShift, *Z_buff, iDirection;
   raster_t* ptr_walls_tex;
   char* ptr_gfx_buffer;
   point_t camera;
   ...
   struct Wall
   {
    point_t p1;
    point_t p2;
   };
   ...
   struct Wall* ptr_wall;
   ...
   cy3d_draw_wall( ptr_gfx_buffer,
      cy3d_warp( ptr_wall->p1, camera, iDirection ),
      cy3d_warp( ptr_wall->p2, camera, iDirection ),
      ptr_walls_tex,
      iIndex,
      iShift,
      Z_buff );
   ...
See also:
cy3d_draw_sprite.

raster_t * cy3d_load ( char * name )

Loads the image collection with the specified name.
If the name of the file ends with the ".spr" the size of the image will be set to 256. Otherwise it will be set to 128. Note: The collection must be linked to the application using the filer utility.

Parameters:
name Name of the image collection. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
Pointer to the image collection
   #include <cywin.h>
   ...
   raster_t* ptr_coll;
   ...
   ptr_coll = cy3d_load( "sign.spr" );
   ...
   free( ptr_coll );
   ...
   ptr_coll = cy3d_load( "wall.tex" );
   ...
   free( ptr_coll );
   ...
See also:
cy3d_load_tex, cy3d_load_spr.

raster_t * cy3d_load_spr ( int index )

Loads the sprite collection with the specified index in the application resource list.
Size of the image will be set to 256. Note: The collection must be linked to the application using the filer utility.

Parameters:
index Index of the collection in the application resource list. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
Pointer to the sprite collection
   #include <cywin.h>
   ...
   raster_t* ptr_obj_spr;
   ...
   ptr_obj_spr = cy3d_load_spr( 5 );
   ...
   free( ptr_obj_spr );
   ...
See also:
cy3d_load, cy3d_load_tex.

raster_t * cy3d_load_tex ( int index )

Loads the texture collection with the specified index in the application resource list.
Size of the image will be set to 128. Note: The collection must be linked to the application using filer utility.

Parameters:
index Index of the collection in the application resource list. Note: cy3d.dl must be loaded on the Cybiko computer.
Returns:
Pointer to the texture collection.
   #include <cywin.h>
   ...
   raster_t* ptr_walls_tex;
   ...
   ptr_walls_tex = cy3d_load_tex( 1 );
   ...
   free( ptr_walls_tex );
   ...
See also:
cy3d_load, cy3d_load_spr.

void cy3d_mirror_buffer ( char * buff )

Copies the top part of the screen to the bottom part of the screen.

Parameters:
buff Pointer to the video buffer. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
None
   #include <cywin.h>
   ...
   struct module_t main_module;
   ...
   init_module( &main_module );
   ...
   char* ptr_video_page =
     DisplayGraphics_get_page_ptr( main_module.m_gfx, 0 );
   ...
   cy3d_mirror_buffer( ptr_video_page );
   ...

point_t cy3d_move ( | point_t p,
 | fixed_t distance,
 | int direction )

Moves a point by a fixed distance in the specified direction.

Parameters:
p | Starting coordinate of the point
distance | Distance the point is to move
direction | Direction of the movement. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
Position of the point after it has moved
   #include <cywin.h>
   ...
   point_t new_position;
   ...
   if( DirectKeyboard_is_key_pressed( ptr_keyboard, KEY_UP ))
   {
     new_position = cy3d_move( camera, 64, direction );
     ...
     if( is_position_acceptable( new_position ))
     {
       camera = new_position;
     }
   }
   ...

point_t cy3d_point ( pos_t p )

Converts the point's coordinates from integer values to fixed point (8.8) values.

Parameters:
p The point's coordinates, represented by integer values. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
The point's coordinates, represented by fixed point (8.8) values

pos_t cy3d_pos ( point_t p )

Converts the point's coordinates, from fixed point (8.8) values to integer values.

Parameters:
p The point's coordinates, represented by fixed point ( 8.8 ) values. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
The pointer's coordinates, represented by integer values

fixed_t cy3d_sin ( int direction )

Calculates sine of the angle.

Parameters:
direction The angle's value (in degrees). Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
Sine of the angle
See also:
cy3d_cos.

int cy3d_sqrt ( long value )

Retrieves square root of the value.

Parameters:
value Nonnegative value whose square root will be obtained Note: cy3d.dl must be loaded to the Cybiko computer.
Returns:
square root of the value.

point_t cy3d_warp ( | point_t p,
 | point_t camera,
 | int direction )

Transforms the point's position in the 3D world to its position in the camera's coordinate system (i.e.
in this coordinate system, the camera is in (0, 0) and directed to the 0Y direction)

Parameters:
p | the point's position before transformation
camera | The camera's position
direction | The camera's direction. Note: cy3d.dl must be loaded on the Cybiko computer
Returns:
the point's position after transformation
   #include <cywin.h>
   ...
   // Coordinates of the Cybiko sign (sprite) in the scene.
   point_t sign_location[ 2 ] =
   {
     { 0, 512 }, { 0, -512 }
   };
   ...
   void render_objects( char* ptr_gfx_buffer,
     point_t camera, int direction, int* z_buffer )
   {
    int index;
    ...
    // Transforms and renders column.
    for( index = 0; index < MAX_COLUMN; index++ )
    {
      cy3d_draw_sprite( ptr_gfx_buffer,
        cy3d_warp( column_location[ index ], camera, direction ),
          ptr_column, 0, z_buffer );
    }
    // Transforms and renders signs.
    for( index = 0; index < MAX_SIGN; index++ )
    {
      int effective_index = ( camera.p_y > 0 ) ? 1 - index : index ;
      ...
      cy3d_draw_sprite( ptr_gfx_buffer,
        cy3d_warp( sign_location[ effective_index ], camera, direction ),
          ptr_sign, sign_frame, z_buffer );
    }
     sign_frame++;
     sign_frame %= 19;
   }
   ...


point_t Struct Reference

Public Attributes
fixed_t p_x
fixed_t p_y

Detailed Description

A point on a plane, with the coordinates represented by fixed point (8.8) values.

See also:
3D Graphics

Member Data Documentation

fixed_t p_x

x-coordinate of the point.

fixed_t p_y

y-coordinate of the point.


pos_t Struct Reference

Public Attributes
short | ps_x
short | ps_y

Detailed Description

A point on a plane, with the coordinates represented by the integer values.

See also:
3D Graphics

Member Data Documentation

short ps_x

x-coordinate of the point.

short ps_y

y-coordinate of the point.


raster_t Struct Reference

Public Attributes
short | r_num
short | r_size
char | r_data [4]

Detailed Description

Collection of sprites or textures used by the CyOS 3D library.

See also:
3D Graphics

Member Data Documentation

char r_data[4]

Data for the images.

short r_num

Number of images in the collection.

short r_size

Size of a single image in the collection.


Fonts and Text

Functions
void | text (int x, int y, struct Font *ptr_font, char *sz_text, int, color_t color)
void | textC (int x, int y, struct Font *ptr_font, char *sz_text, int width, color_t color, color_t bk_color)
int | draw_bounded_text (struct Graphics *ptr_gfx, int x, int y, int width, char *sz_text)

Compounds
struct Font Provides functions for manipulating the appearance of text characters

Detailed Description

Some structures for work with text (please pay attention to Font structure).

Function Documentation

int draw_bounded_text ( | struct Graphics * ptr_gfx,
 | int x,
 | int y,
 | int width,
 | char * sz_text )

Draws bounded text with trailing dots if text is cut.

Parameters:
ptr_gfx | a pointer to the graphics context.
x | the x-coordinate of a text block.
y | the y-coordinate of a text block.
width | the width of a text block (in symbols).
sz_text | a pointer to the text to be drawn.
Returns:
The number of characters actually drawn, not including dots.
        #include <cywin.h>
        ...
        struct module_t  main_module;
        ...
        init_module( &main_module );
        ...
        draw_bounded_text( main_module.m_gfx, 10, 10, 4, "Any text" );
        ...

void text ( | int x,
 | int y,
 | struct Font * ptr_font,
 | char * sz_text,
 | int,
 | color_t color )

Draws text in the specified color.

Parameters:
x | the x-coordinate of the upper-left corner.
y | the y-coordinate of the upper-left corner.
ptr_font | the pointer to the initialized font structure.
sz_text | a pointer to the string of a text to be drawn.
width | the width of a text block (in symbols).
color | the text color.
Returns:
None.
        #include <cywin.h>
        ...
        text( 10, 10, cool_normal_font, "Any text", 6, CLR_DKGRAY );
        ...

void textC ( | int x,
 | int y,
 | struct Font * ptr_font,
 | char * sz_text,
 | int width,
 | color_t color,
 | color_t bk_color )

Draws text with specified colors for the text and the background.

Parameters:
x | the x-coordinate of the upper-left corner.
y | the y-coordinate of the upper-left corner.
ptr_font | a pointer to the initialized font structure.
sz_text | a pointer to the string of a text to be drawn.
width | the width of a text block (in symbols).
color | the text color.
bk_color | the background color.
Returns:
None.
        #include <cywin.h>
        ...
        textC( 10, 10, cool_normal_font, "Any text", 3, CLR_WHITE, CLR_BLACK );
        ...


Font Struct Reference

Inheritance diagram for Font

Collaboration diagram for Font:

Public Methods
struct Font* | Font_ctor (struct Font *ptr_font)
struct Font* | Font_ctor_Ex (struct Font *ptr_font, char *file_name, bool fixed, int spacing)
void | Font_dtor (struct Font *ptr_font, int memory_flag)
char* | Font_get_name (struct Font *ptr_font)
void | Font_set_name (struct Font *ptr_font, char *filename)
int | Font_get_char_width (struct Font *ptr_font, int chr)
int | Font_string_width (struct Font *ptr_font, char *str)
int | Font_string_width_Ex (struct Font *ptr_font, char *str, int len)
int | Font_get_char_height (struct Font *ptr_font)
bool | Font_is_fixed (struct Font *ptr_font)
void | Font_set_fixed (struct Font *ptr_font, bool fixed)
int | Font_get_spacing (struct Font *ptr_font)
void | Font_set_spacing (struct Font *ptr_font, int spacing)
bool | Font_load (struct Font *ptr_font, struct Input *input)
struct Bitmap* | Font_bmp_by_char (struct Font *ptr_font, int chr)
char* | Font_split_string (struct Font *ptr_font, char **str, int width, int *len)
int | Font_get_size (struct Font *ptr_font)
int | Font_get_x (struct Font *ptr_font, int bitmap_index)
int | Font_get_y (struct Font *ptr_font, int bitmap_index)
struct Bitmap* | Font_get_bitmap (struct Font *ptr_font, int bitmap_index)
bool | Font_store (struct Font *ptr_font, struct Output *output)

Public Attributes
struct Font* | cool_bold_font
struct Font* | cool_normal_font
struct Font* | mini_bold_font
struct Font* | mini_normal_font

Detailed Description

To use a Font object, construct it with the Font_ctor or Font_ctor_Ex functions. Use Font_dtor to deconstruct a Font object after use. Font object operations include receiving information about the character width and height, string length or length of a predefined number of characters in a string; as well as receiving the Bitmap representation of any character in a string.

You can fix the current font by calling the Font_set_fixed function. You can set the font spacing value by calling the Font_set_spacing function. You can also use the extended version of the Font_ctor function, which calls Font_ctor_Ex and enables it to create a font object using a resource.

Since all characters in a text string are elements of a BitmapSequence object, you can manipulate a text string as if it were a BitmapSequence object.

See also:
Fonts and Text

Member Function Documentation

struct Bitmap * Font_bmp_by_char ( | struct Font * ptr_font,
 | int chr )

Returns the bitmap object of the 'chr' character.
(Bitmap representation of the 'chr' character).

Parameters:
ptr_font | A pointer to the initialized Font object
chr | A character
Returns:
A pointer to a Bitmap object that represents the 'chr' character
   #include <cybiko.h>
     ...
     struct Font   font;
     struct Bitmap * bmp;
     ...
     Font_ctor_Ex( &font, "MyFont.fnt", TRUE, 5 );
     ...
     bmp = Font_bmp_by_char( &font, 'c' );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
     Bitmap_dtor( bmp, FREE_MEMORY );

struct Font * Font_ctor ( struct Font * ptr_font )

A simple Font constructor.
Creates an empty Font object.

Parameters:
ptr_font A pointer to the Font structure
Returns:
A pointer to the initialized Font object
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor( &font );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_ctor_Ex.

struct Font * Font_ctor_Ex ( | struct Font * ptr_font,
 | char * file_name,
 | bool fixed,
 | int spacing )

The extended version of the Font_ctor function.
It creates a Font object from a file.

Parameters:
ptr_font | A pointer to the Font structure
file_name | The name of a file that contains a font
fixed | sets TRUE for fonts with a fixed width
spacing | The font spacing value in pixels
Returns:
A pointer to the initialized Font object
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor_Ex( &font, "MyFont.fnt", TRUE, 5 );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_ctor.

void Font_dtor ( | struct Font * ptr_font,
 | int memory_flag )

Destructor.
Deletes a Font object.

Parameters:
ptr_font | A pointer to the initialized Font object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stackcan
Returns:
None
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor( &font );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct Bitmap * Font_get_bitmap ( | struct Font * ptr_font,
 | int bitmap_index )

Returns a pointer to the bitmap with a specified index.

Parameters:
ptr_font | A pointer to the initialized Font object
bitmap_index | The bitmap's index
Returns:
A pointer to the bitmap with the specified index

int Font_get_char_height ( struct Font * ptr_font )

Returns the character's height in pixels.

Parameters:
ptr_font A pointer to the initialized Font object
Returns:
The character's height in pixels
   #include <cybiko.h>
     ...
     struct Font font;
     int char_height;
     ...
     Font_ctor( &font );
     ...
     char_height = Font_get_char_height( &font );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_get_char_width.

int Font_get_char_width ( | struct Font * ptr_font,
 | int chr )

Returns the character's width in pixels.

Parameters:
ptr_font | A pointer to the initialized Font object
chr | A character
Returns:
The character's width in pixels
   #include <cybiko.h>
     ...
     struct Font font;
     int char_width;
     Font_ctor( &font );
     ...
     char_width = Font_get_char_width( &font, 'c' );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_get_char_height, Font_string_width.

char * Font_get_name ( struct Font * ptr_font )

Returns the font name.
This is equal to the full font file name.

Parameters:
ptr_font A pointer to the initialized Font object
Returns:
The font name
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor( &font );
     ...
     char*  ptr_font_name;
     ptr_font_name = Font_get_name( &font );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_set_name.

int Font_get_size ( struct Font * ptr_font )

Returns the number of bitmaps in a font object.

Parameters:
ptr_font A pointer to the initialized Font object
Returns:
The number of bitmaps in a font object

int Font_get_spacing ( struct Font * ptr_font )

Returns the font spacing value.

Parameters:
ptr_font A pointer to the initialized Font object
Returns:
The font spacing value
   #include <cybiko.h>
     ...
     struct Font font;
     int    font_space;
     Font_ctor_Ex( &font, "MyFont.fnt", TRUE, 5 );
     ...
     font_space = Font_get_spacing( &font );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_set_spacing.

int Font_get_x ( | struct Font * ptr_font,
 | int bitmap_index )

Returns the X origin of the Nth bitmap in a font object.

Parameters:
ptr_font | A pointer to the initialized Font object
bitmap_index | The bitmap's index
Returns:
The X origin of the Nth bitmap in a font object
See also:
Font_get_y

int Font_get_y ( | struct Font * ptr_font,
 | int bitmap_index )

Returns the Y origin of the Nth bitmap in a font object.

Parameters:
ptr_font | A pointer to the initialized Font object
bitmap_index | The bitmap's index
Returns:
The Y origin of the Nth bitmap in a font object
See also:
Font_get_x

bool Font_is_fixed ( struct Font * ptr_font )

Determines if the font is fixed.

Parameters:
ptr_font A pointer to the initialized Font object
Returns:
TRUE if the font is fixed
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor_Ex( &font, "MyFont.fnt", TRUE, 5 );
     ...
     if ( !Font_is_fixed( &font ) )
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_set_fixed.

bool Font_load ( | struct Font * ptr_font,
 | struct Input * input )

Loads the font from an opened stream.

Parameters:
ptr_font | A pointer to the initialized Font object
input | A pointer to an opened stream
Returns:
TRUE if the font was loaded successfully
   #include <cybiko.h>
     ...
     struct Input * ptr_input;
     struct Font  font;
     ...
     // Your make file must have the archive resource "bmp.pic" linked by filer.exe.
     // For example, see the Cybiko Compiler's Introduction Section.
     ptr_input = open_resource_Ex( "font_1.pic" );
     ...
     if( !Font_load( &font, ptr_input ) )
     ...
     Font_dtor( &font, LEAVE_MEMORY );
     Input_dtor( ptr_input, FREE_MEMORY );

void Font_set_fixed ( | struct Font * ptr_font,
 | bool fixed )

Sets or doesn't set a fixed font.

Parameters:
ptr_font | A pointer to the initialized Font object
fixed | TRUE if it's need to set a fixed font
Returns:
None
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor_Ex( &font, "MyFont.fnt", TRUE, 5 );
     ...
     Font_set_fixed( &font, FALSE );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_is_fixed.

void Font_set_name ( | struct Font * ptr_font,
 | char * filename )

Sets the font name manually.

Parameters:
ptr_font | A pointer to the initialized Font object
filename | The file name
Returns:
None
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor( &font );
     ...
     Font_set_name( &font, "MyFont.fnt" );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_get_name.

void Font_set_spacing ( | struct Font * ptr_font,
 | int spacing )

Sets the font spacing value.

Parameters:
ptr_font | A pointer to the initialized Font object
spacing | A font's spacing value
Returns:
None
   #include <cybiko.h>
     ...
     struct Font font;
     Font_ctor_Ex( &font, "MyFont.fnt", TRUE, 5 );
     ...
     if ( Font_get_spacing( &font ) < 3 )
       Font_set_spacing( &font, 5 );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_get_spacing.

char * Font_split_string ( | struct Font * ptr_font,
 | char ** str,
 | int width,
 | int * len )

Splits string str to substrings that fit specified width.
This function doesn't modify the source string, but calculates start and length of each substring instead.

The first call to this function returns an address of the source string and calculates first substring's length. Subsequent calls return remaining substrings' addresses and lengths, in order.

The string may contain explicit line breaks ('\n').

Parameters:
ptr_font | A pointer to a font which metrics will be used to measure the string width
str | A string to be splitted; this parameter is modified by the function to handle subsequent calls
width | Width, in pixels, to fit the source text in
len | Returns length of the current substring, in characters
Returns:
A pointer to the current substring, or NULL if no text is left
   #include <cybiko.h>
     ...
     char *str, *ptr;
     int  len;
     ...
     str = "Any   string";
     while( ptr = Font_split_string( &str, 6, &len ))
     {
       draw_text( ptr, 0, y*12, len );
       y++;
     }

bool Font_store ( | struct Font * ptr_font,
 | struct Output * output )

Stores a font object to an opened stream.

Parameters:
ptr_font | A pointer to the initialized Font object
output | A pointer to the Output stream
Returns:
TRUE if the font sequence was stored successfully

int Font_string_width ( | struct Font * ptr_font,
 | char * str )

Returns the string's width in pixels.

Parameters:
ptr_font | A pointer to the initialized Font object
str | A string
Returns:
The string's width in pixels
   #include <cybiko.h>
     ...
     struct Font font;
     int    str_width;
     char*  str = "any string";
     ...
     Font_ctor( &font );
     ...
     str_width = Font_string_width( &font, str );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_get_char_width, Font_string_width_Ex.

int Font_string_width_Ex ( | struct Font * ptr_font,
 | char * str,
 | int len )

The extended version of the Font_string_width function.
This function returns the width in pixels of the first 'flen' characters of a string.

Parameters:
ptr_font | A pointer to the initialized Font object
str | A string
len | The number of characters needed
Returns:
The string's width in pixels
   #include <cybiko.h>
     ...
     struct Font font;
     int    str_width;
     char*  str = "any string";
     ...
     Font_ctor( &font );
     ...
     str_width = Font_string_width_Ex( &font, str, 3 );
     ...
     Font_dtor( &font, LEAVE_MEMORY );
See also:
Font_string_width, Font_get_char_width.

Member Data Documentation

struct Font * cool_bold_font

Handle for the 'cool bold' font.

struct Font * cool_normal_font

Handle for the 'cool normal' font.

struct Font * mini_bold_font

Handle for the 'mini bold' font.

struct Font * mini_normal_font

Handle for the 'mini normal' font.


Application

Compounds
struct | AppGeneric | The base structure for applications
struct | cWinApp | The cWinApp structure is your application object

Detailed Description

These structures represent applications' major building blocks. In fact, your application is an instance of cWinApp (please note that module_t structure contains m_process field that is a pointer to 'your' instance), which is important, since it allows for the usage of forms, controls, as well as other interface elements.


AppGeneric Struct Reference

Inheritance diagram for AppGeneric

Collaboration diagram for AppGeneric:

Public Methods
struct DisplayGraphics* | AppGeneric_init_display (void)
void | AppGeneric_clear_screen (void)
bool | AppGeneric_proc (struct AppGeneric *ptr_app_generic, struct Message *ptr_message)
void | AppGeneric_cancel_shutup (struct AppGeneric *ptr_app_generic)
void | AppGeneric_ext_cancel_shutup (void)
bool | AppGeneric_pause (struct AppGeneric *ptr_app_generic, clock_t timeout)
struct Process* | AppGeneric_request_focus (struct Process *ptr_app_generic)
bool | AppGeneric_has_focus (struct AppGeneric *ptr_app_generic)
struct DisplayGraphics* | AppGeneric_get_display (void)
struct Message* | AppGeneric_peek_message (struct AppGeneric *ptr_app_generic, bool remove, int min, int max)
struct Message* | AppGeneric_get_message (struct AppGeneric *ptr_app_generic, long timeout, int min, int max)
void | AppGeneric_put_message (struct AppGeneric *ptr_app_generic, struct Message *ptr_message)
char* | AppGeneric_get_name (struct AppGeneric *ptr_app_generic)

Detailed Description

AppGeneric is a simple application structure. In other words, it is the base structure for applications. It implements such functions as: receiving the graphics context for application needs, cleaning the screen, processing messages and canceling MSG_SHUTUP events. This object cannot be instantiated! It can be obtained using init_module().

See also:
Application

Member Function Documentation

void AppGeneric_cancel_shutup ( struct AppGeneric * ptr_app_generic )

Cancels the MSG_SHUTUP message.
Cancels a task switch operation previously launched by another application in the task manager, and deletes any MSG_SHUTUP messages from the message queue. Requires the AppGeneric object pointer.

Parameters:
ptr_app_generic A pointer to initialized AppGeneric object.
Returns:
None
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       struct Message* ptr_message;
       ...
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_USER );
       if( ptr_message->msgid == MSG_SHUTUP )
       {
         //  We do not need to exit.
         //  Cancels shutup and deletes all MSG_SHUTUP messages.
         AppGeneric_cancel_shutup(  main_module.m_process );
         ...
       }
       ...
See also:
MSG_SHUTUP

void AppGeneric_clear_screen ( void )

Clears the screen with a white color.

Returns:
None
       #include <cybiko.h>
       ...
       struct DisplayGraphics* ptr_gfx;
       ...
       //  Clears the screen.
       AppGeneric_clear_screen();
       ...
       //  Draws a filled rectangle.
       ptr_gfx = AppGeneric_init_display();
       DisplayGraphics_set_color( ptr_gfx , CLR_BLACK );
       DisplayGraphics_fill_rect( ptr_gfx , 5, 5, 30, 30 );
       DisplayGraphics_show( ptr_gfx );
       ...

void AppGeneric_ext_cancel_shutup ( void )

Cancels the MGS_SHUTUP message statically.
Used to cancel a task switch operation previously launched by another application in the task manager. Doesn't require the AppGeneric object pointer, but doesn't delete any MSG_SHUTUP messages.

Returns:
None
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       struct Message* ptr_message;
       ...
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_USER );
       if( ptr_message->msgid == MSG_SHUTUP )
       {
         //  We do not need to exit.
         //  Cancels shutup.
         AppGeneric_ext_cancel_shutup();
         ...
       }
       ...
See also:
MSG_SHUTUP

struct DisplayGraphics * AppGeneric_get_display ( void )

Retrieves DisplayGraphics object to access the Cybiko display.

Returns:
A pointer to the DisplayGraphics object
      #include <cybiko.h>
      ...
      struct Bitmap bmp;
      ...
      //  Creates a bitmap from the file "root.ico".
      Bitmap_ctor_Ex1( &bmp, "root.ico" );
      ...
      //  Draws bitmap.
      DisplayGraphics_draw_bitmap( AppGeneric_get_display(),
                                   &bmp,
                                   30,
                                   40,
                                   BM_NORMAL );
      DisplayGraphics_show( AppGeneric_get_display() );
      ...
      Bitmap_dtor( &bmp, LEAVE_MEMORY );
      ...

struct Message * AppGeneric_get_message ( | struct AppGeneric * ptr_app_generic,
 | long timeout,
 | int min,
 | int max )

Returns the message for the specified interval.
The calling thread waits until the first message appears in the queue. Be careful, not to overload the queue. Delete the message when you are finished with it.

Parameters:
ptr_app_generic | A pointer to initialized AppGeneric object
timeout | Timeout value(in milliseconds)
min | Deprecated
max | Deprecated
Returns:
Pointer to the Message if there is one in the process' queue, or 0 if a timeout occurs
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_USER );
       if( ptr_message->msgid == MSG_KEYDOWN )
       {
         if( Message_get_key_param( ptr_message )->scancode == MSG_ESC )
         {
           //  Processes 'Esc' key.
         }
       }
       ...
       Message_delete( ptr_message );
       ...
See also:
AppGeneric_put_message, AppGeneric_peek_message.

char * AppGeneric_get_name ( struct AppGeneric * ptr_app_generic )

Retrieves the name of the application.

Parameters:
ptr_app_generic A pointer to an initialized AppGeneric object
Returns:
The name of the application
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       TRACE( "Hello from the %s application",
             AppGeneric_get_name( main_module.m_process ) );
       ...

bool AppGeneric_has_focus ( struct AppGeneric * ptr_app_generic )

Tests whether the process has the device's focus.

Parameters:
ptr_app_generic A pointer to an initialized AppGeneric object
Returns:
TRUE if the application has the focus
      #include <cybiko.h>
      ...
      AppGeneric_request_focus( main_module.m_process );
      ...
      if( AppGeneric_has_focus( main_module.m_process ) )
      {
        // Draws something.
        ...
      }
      ...

struct DisplayGraphics * AppGeneric_init_display ( void )

Obtains the graphics context.

Returns:
A pointer to a DisplayGraphics object
       #include <cybiko.h>
       ...
       struct DisplayGraphics* ptr_gfx;
       ...
       // Clears the screen.
       AppGeneric_clear_screen();
       ...
       // Draws a filled rectangle.
       ptr_gfx = AppGeneric_init_display();
       DisplayGraphics_set_color( ptr_gfx , CLR_BLACK );
       DisplayGraphics_fill_rect( ptr_gfx , 5, 5, 30, 30 );
       DisplayGraphics_show( ptr_gfx );
       ...

bool AppGeneric_pause ( | struct AppGeneric * ptr_app_generic,
 | clock_t timeout )

Pauses execution of the application.

Parameters:
ptr_app_generic | A pointer to an initialized AppGeneric object
timeout | The time span for sleeping
Returns:
FALSE if timeout has passed
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone( 30 );
       AppGeneric_pause( main_module.m_process, 200 );
       play_tone( -1 );
       ...

struct Message * AppGeneric_peek_message ( | struct AppGeneric * ptr_app_generic,
 | bool remove,
 | int min,
 | int max )

Peeks or gets a message from the queue.
If 'remove' is TRUE, the message will be removed. This function does not wait for a message to be available; it returns 0 immediately if there are no messages in the specified range. Don't use it unless you really need to.

Parameters:
ptr_app_generic | A pointer to the initialized AppGeneric object
remove | If TRUE, the message will be removed from the message queue
min | Specifies the integer value of the lowest message value to be retrieved
max | Specifies the integer value of the highest message value to be retrieved
Returns:
Pointer to the Message if there is one in the process' queue; otherwise 0
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       //  Removes all keyboard messages from the queue.
       while( ptr_message = AppGeneric_peek_message( main_module.m_process,
                                                     TRUE,
                                                     MSG_KEYDOWN,
                                                     MSG_KEYDOWN ) )
       {
         Message_delete( ptr_message );
       }
       ...
See also:
AppGeneric_get_message.

bool AppGeneric_proc ( | struct AppGeneric * ptr_app_generic,
 | struct Message * ptr_message )

Provides generic message processing.
Should be called on every message that the user doesn't process.

Parameters:
ptr_app_generic | A pointer to the initialized AppGeneric object
ptr_message | A pointer to aprocessed Message
Returns:
TRUE if the message was processed
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       //  Sets the resource "0.help" as the help file
       main_module.m_process->HelpContext = 0;
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_USER );
       //  The help screen appears if the user presses the '?' button
       AppGeneric_proc( main_module.m_process, ptr_message );
       ...

void AppGeneric_put_message ( | struct AppGeneric * ptr_app_generic,
 | struct Message * ptr_message )

Puts a Message in the application's Queue.

Parameters:
ptr_app_generic | A pointer to the initialized AppGeneric object
ptr_message | A pointer to the message to send
Returns:
None.
       #include <cybiko.h>
       #define MSG_MAKE_TASK  MSG_USER + 1
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_MAKE_TASK );
       if( ptr_message->msgid == MSG_MAKE_TASK )
       {
         ...
         //  Performs some periodical calculation.
         ...
         sleep( 250 );
         AppGeneric_put_message( main_module.m_process, ptr_message );
       }
       else
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Process_get_message, Process_peek_message.

struct Process * AppGeneric_request_focus ( struct Process * ptr_app_generic )

Requests that the application receive the focus.
The application with the focus has actual access to the screen and receives the keyboard and pointing device events. When the system gets this call, it passes the focus to the process that requested it and sends it the message MSG_GOTFOCUS. After that, the system sends the message MSG_LOSTFOCUS to the process that had the focus before this call.

Parameters:
ptr_app_generic A pointer to the initialized AppGeneric object
Returns:
A pointer to the Process object that had the focus before this call
      #include <cybiko.h>
      ...
      AppGeneric_request_focus( main_module.m_process );
      ...
      if( AppGeneric_has_focus( main_module.m_process ) )
      {
        //  Draws something.
        ...
      }
      ...
See also:
MSG_GOTFOCUS, MSG_LOSTFOCUS


cWinApp Struct Reference

Inheritance diagram for cWinApp

Collaboration diagram for cWinApp:

Public Methods
bool | cWinApp_defproc (struct cWinApp *ptr_win_app, struct Message *ptr_message)
bool | cWinApp_pause (struct cWinApp *ptr_win_app, clock_t timeout)
struct DisplayGraphics* | cWinApp_init_display (void)
void | cWinApp_clear_screen (void)
void | cWinApp_cancel_shutup (struct cWinApp *ptr_win_app)
void | cWinApp_ext_cancel_shutup (void)
struct Process* | cWinApp_request_focus (struct cWinApp *ptr_win_app)
bool | cWinApp_has_focus (struct cWinApp *ptr_win_app)
struct DisplayGraphics* | cWinApp_get_display (void)
struct Message* | cWinApp_peek_message (struct cWinApp *ptr_win_app, bool remove, int min, int max)
struct Message* | cWinApp_get_message (struct cWinApp *ptr_win_app, long timeout, int min, int max)
void | cWinApp_put_message (struct cWinApp *ptr_win_app, struct Message *ptr_message)
char* | cWinApp_get_name (struct cWinApp *ptr_win_app)
void | cWinApp_Disconnect (struct cWinApp *ptr_win_app)
bool | cWinApp_Select (struct cWinApp *ptr_win_app)
void | cWinApp_update (struct cWinApp *ptr_win_app)
struct cClip* | cWinApp_GetParent (struct cWinApp *ptr_win_app)
void | cWinApp_Hide (struct cWinApp *ptr_win_app)
void | cWinApp_Show (struct cWinApp *ptr_win_app)
void | cWinApp_Disable (struct cWinApp *ptr_win_app)
void | cWinApp_Enable (struct cWinApp *ptr_win_app)
void | cWinApp_AddObj (struct cWinApp *ptr_win_app, struct cObject *ptr_object, int x, int y)
void | cWinApp_InsObj (struct cWinApp *ptr_win_app, struct cObject *ptr_object, int x, int y, int index)
void | cWinApp_RemObj (struct cClip *ptr_win_app, struct cObject *ptr_object)
bool | cWinApp_SelectFirst (struct cWinApp *ptr_win_app)
bool | cWinApp_SelectPrev (struct cWinApp *ptr_win_app, bool round)
bool | cWinApp_SelectNext (struct cWinApp *ptr_win_app, bool round)
void | cWinApp_Scroll (struct cWinApp *ptr_win_app, struct rect_t *rectangle)
void | cWinApp_Scroll_Ex (struct cWinApp *ptr_win_app, int x, int y)
void | cWinApp_SendScroll (struct cWinApp *ptr_win_app)
int | cWinApp_GetShifty (struct cWinApp *ptr_win_app)
int | cWinApp_GetShiftx (struct cWinApp *ptr_win_app)
int | cWinApp_GetCount (struct cWinApp *ptr_win_app)
struct cObject* | cWinApp_get_by_index (struct cWinApp *ptr_win_app, int index)
int | cWinApp_FindObj (struct cWinApp *ptr_win_app, struct cObject *ptr_object)
struct cObject* | cWinApp_GetSelectedObject (struct cWinApp *ptr_win_app)

Detailed Description

The cWinApp structure is your application object. It implements cywin's functions, to work with user's objects such as: cBitmap, cEdit, cList, cItem, etc.

You must make a pointer to it using the init_module function.

See also:
Application

Member Function Documentation

void cWinApp_AddObj ( | struct cWinApp * ptr_win_app,
 | struct cObject * ptr_object,
 | int x,
 | int y )

Adds an object to the cWinApp in position (x, y).

Parameters:
ptr_win_app | A pointer to the initialized cWinApp structure
ptr_object | A pointer to the initialized cObject structure
x | x-coordinate of the new object
y | y-coordinate of the new object
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     // It's the same as using the cClip_AddObj( &button ) function.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

void cWinApp_Disable ( struct cWinApp * ptr_win_app )

Disables a cWinApp object so that it cannot be selected.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
None

void cWinApp_Disconnect ( struct cWinApp * ptr_win_app )

Disconnects a cWinApp from its parent object.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
None

void cWinApp_Enable ( struct cWinApp * ptr_win_app )

Enables a cWinApp object so that it may be selected.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
None

int cWinApp_FindObj ( | struct cWinApp * ptr_win_app,
 | struct cObject * ptr_object )

Returns a child object's index in cWinApp (or -1).

Parameters:
ptr_win_app | A pointer to the initialized cClip structure
ptr_object | A pointer to the needed cObject
Returns:
The child object's index in cWinApp (or -1).
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     struct cObject * currentObj;
     int nButtonNumber;
     int i;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
      // Finds the object.
     if ( cWinApp_FindObj( main_module.m_process, &button2 ) != -1 )
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

int cWinApp_GetCount ( struct cWinApp * ptr_win_app )

Returns a count of child objects.

Parameters:
ptr_win_app A pointer to the initialized cClip structure
Returns:
Child objects count
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     int nButtonNumber;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
     // nButtonNumber will be equal to 3.
     nButtonNumber = cWinApp_GetCount( main_module.m_process );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

struct cClip * cWinApp_GetParent ( struct cWinApp * ptr_win_app )

Returns a pointer to the parent object.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
A pointer to the parent object

struct cObject * cWinApp_GetSelectedObject ( struct cWinApp * ptr_win_app )

Returns the currently selected object.

Parameters:
ptr_win_app A pointer to the initialized cClip structure
Returns:
The currently selected object
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     struct cObject * selectedObj;
     int nButtonNumber;
     int i;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
     cObject_Select( &button2 );
     ...
     // Redraws selected objects.
     cButton_update( cWinApp_GetSelectedObject( main_module.m_process );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

int cWinApp_GetShiftx ( struct cWinApp * ptr_win_app )

Returns the 'x' coordinate shift (as a result of scrolling).

Parameters:
ptr_win_app A pointer to the initialized cClip structure
Returns:
'x' coordinate shift (as a result of scrolling).
   #include <cywin.h>
     ...
     struct cBitmap cbmp;
     struct Bitmap bmp;
     struct module_t main_module;
     int nShift_X;
     ...
     init_module( &main_module );
     ...
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     cBitmap_ctor( &cbmp, &bmp );
     // Puts the cBitmap object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
     ...
     // Scrolls the bitmap to the visible area.
     cWinApp_Scroll_Ex( main_module.m_process, -160, -240 );
     cWinApp_SendScroll( main_module.m_process );
     // nShift_X will be equal to -160.
     nShift_X = cWinApp_GetShiftx( main_module.m_process );
     ...
     cBitmap_dtor( &cbmp, LEAVE_MEMORY );
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
See also:
cWinApp_GetShifty.

int cWinApp_GetShifty ( struct cWinApp * ptr_win_app )

Returns the 'y' coordinate shift (as a result of scrolling).

Parameters:
ptr_win_app A pointer to the initialized cClip structure
Returns:
'y' coordinate shift (as a result of scrolling)
   #include <cywin.h>
     ...
     struct cBitmap cbmp;
     struct Bitmap bmp;
     struct module_t main_module;
     int nShift_Y;
     ...
     init_module( &main_module );
     ...
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     cBitmap_ctor( &cbmp, &bmp );
     // Puts the cBitmap object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
     ...
     // Scrolls the bitmap to the visible area.
     cWinApp_Scroll_Ex( main_module.m_process, -160, -240 );
     cWinApp_SendScroll( main_module.m_process );
     // nShift_Y will be equal to -240.
     nShift_Y = cWinApp_GetShifty( main_module.m_process );
     ...
     cBitmap_dtor( &cbmp, LEAVE_MEMORY );
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...
See also:
cWinApp_GetShiftx.

void cWinApp_Hide ( struct cWinApp * ptr_win_app )

Hides a cWinApp object.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
None
See also:
cWinApp_Show.

void cWinApp_InsObj ( | struct cWinApp * ptr_win_app,
 | struct cObject * ptr_object,
 | int x,
 | int y,
 | int index )

Adds an object to the cWinApp in position (x, y) with a z-position index (maximal index is on the top).

Parameters:
ptr_win_app | A pointer to the initialized cWinApp structure
ptr_object | A pointer to the initialized cObject structure
x | x-coordinate of the new object
y | y-coordinate of the new object
index | The index of the new object's z-position
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

void cWinApp_RemObj ( | struct cClip * ptr_win_app,
 | struct cObject * ptr_object )

Removes an object from cWinApp.

Parameters:
ptr_win_app | A pointer to the initialized cClip structure
ptr_object | A pointer to the initialized cObject structure
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     // It's the same as using the cClip_AddObj( &button ) function.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // It's the same as using the cClip_RemObj( &button ) function.
     cClip_RemObj( main_module.m_process, &button );
     cButton_dtor( &button, LEAVE_MEMORY );

void cWinApp_Scroll ( | struct cWinApp * ptr_win_app,
 | struct rect_t * rectangle )

Scrolls a cWinApp to make a rectangle visible.
Provides minimal scrolling.

Parameters:
ptr_win_app | A pointer to the initialized cClip structure
rectangle | A pointer to the initialized rect_t structure
Returns:
None
   #include <cywin.h>
     ...
     struct cBitmap cbmp;
     struct Bitmap bmp;
     struct module_t main_module;
     struct rect_t rect;
     ...
     init_module( &main_module );
     ...
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     cBitmap_ctor( &cbmp, &bmp );
     // Puts the cBitmap object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
     ...
     rect_set( &rect, 160, 240, bmp.h, bmp.w );
     // Scrolls the bitmap to the visible area.
     cWinApp_Scroll( main_module.m_process, &rect );
     ...
     cBitmap_dtor( &cbmp, LEAVE_MEMORY );
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...
See also:
cWinApp_Scroll_Ex.

void cWinApp_Scroll_Ex ( | struct cWinApp * ptr_win_app,
 | int x,
 | int y )

Scrolls a cWinApp by (x, y), but cannot exceed the child's boundaries.

Parameters:
ptr_win_app | A pointer to the initialized cClip structure
x | An "x" coordinate shift
y | An "y" coordinate shift
Returns:
None
   #include <cywin.h>
     ...
     struct cBitmap cbmp;
     struct Bitmap bmp;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     cBitmap_ctor( &cbmp, &bmp );
     // Puts the cBitmap object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
     ...
     rect_set( &rect, 160, 240, bmp.h, bmp.w );
     // Scrolls the bitmap to the visible area.
     cWinApp_Scroll_Ex( main_module.m_process, -160, -240);
     ...
     cBitmap_dtor( &cbmp, LEAVE_MEMORY );
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...
See also:
cWinApp_Scroll.

bool cWinApp_Select ( struct cWinApp * ptr_win_app )

Selects a cWinApp object.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
TRUE if the object was selected

bool cWinApp_SelectFirst ( struct cWinApp * ptr_win_app )

Selects the first object in the cWinApp.

Parameters:
ptr_win_app A pointer to the initialized cClip structure
Returns:
FALSE if the function failed.
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
     // Selects the first button.
     cWinApp_SelectFirst( main_module.m_process );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
cWinApp_SelectPrev, cWinApp_SelectNext.

bool cWinApp_SelectNext ( | struct cWinApp * ptr_win_app,
 | bool round )

Selects the next object in the cWinApp.

Parameters:
ptr_win_app | A pointer to the initialized cClip structure
round | TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
     // Selects the first button.
     cWinApp_SelectFirst( main_module.m_process );
     ...
     // Selects the next button.
     cWinApp_SelectNext( main_module.m_process , TRUE);
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
cWinApp_SelectFirst, cWinApp_SelectPrev.

bool cWinApp_SelectPrev ( | struct cWinApp * ptr_win_app,
 | bool round )

Selects the previous object in cWinApp.

Parameters:
ptr_win_app | A pointer to the initialized cClip structure
round | TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
     // Selects the first button.
     cWinApp_SelectFirst( main_module.m_process );
     ...
     // Selects the previous button.
     cWinApp_SelectPrev( main_module.m_process , TRUE);
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
cWinApp_SelectFirst, cWinApp_SelectNext.

void cWinApp_SendScroll ( struct cWinApp * ptr_win_app )

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_win_app A pointer to the initialized cClip structure
Returns:
None
   #include <cywin.h>
     ...
     struct cBitmap cbmp;
     struct Bitmap bmp;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     cBitmap_ctor( &cbmp, &bmp );
     // Puts the cBitmap object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
     ...
     // Scrolls the bitmap to the visible area.
     cWinApp_Scroll_Ex( main_module.m_process, -160, -240 );
     cWinApp_SendScroll( main_module.m_process );
     ...
     cBitmap_dtor( &cbmp, LEAVE_MEMORY );
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...

void cWinApp_Show ( struct cWinApp * ptr_win_app )

Shows a cWinApp object.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
None
See also:
cWinApp_Hide.

void cWinApp_cancel_shutup ( struct cWinApp * ptr_win_app )

Cancels the MSG_SHUTUP message.
Used to cancel a task switch operation previously launched by another application in the task manager. Deletes all MSG_SHUTUP messages from the message queue. Requires a cWinApp object pointer.

Parameters:
ptr_win_app A pointer to the cWinApp initialized structure
Returns:
None
   #include <cywin.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if( ptr_message->msgid == MSG_SHUTUP)
     {
       // We cancel shutup and delete all MSG_SHUTUP messages.
       cWinApp_cancel_shutup( main_module.m_process );
       ...
     }
     ...
See also:
MSG_SHUTUP, cWinApp_ext_cancel_shutup.

void cWinApp_clear_screen ( void )

Clears the screen with the color white.

Returns:
None
   #include <cywin.h>
     ...
     struct DisplayGraphics* ptr_gfx;
     ...
     // Clears the screen.
     cWinApp_clear_screen();
     ...
     // Draws the filled rectangle.
     ptr_gfx = cWinApp_init_display();
     DisplayGraphics_set_color( ptr_gfx , CLR_BLACK );
     DisplayGraphics_fill_rect( ptr_gfx , 5, 5, 30, 30 );
     DisplayGraphics_show( ptr_gfx );
     ...

bool cWinApp_defproc ( | struct cWinApp * ptr_win_app,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_win_app | A pointer to the cWinApp object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed
   #include <cywin.h>
     ...
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       //  If user presses the '?' button, help will be shown.
       cWinApp_defproc( main_module.m_process, ptr_message);
     }
     ...

void cWinApp_ext_cancel_shutup ( void )

Cancels the MGS_SHUTUP message statically.
Used to cancel a task switch operation previously launched by another application in the task manager. Doesn't require a cWinApp object pointer, but doesn't delete any other MSG_SHUTUP messages.

Returns:
None
   #include <cywin.h>
     ...
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if( ptr_message->msgid == MSG_SHUTUP)
     {
       // We cancel shutup.
       cWinApp_ext_cancel_shutup();
       ...
     }
     ...
See also:
MSG_SHUTUP, cWinApp_cancel_shutup.

struct cObject * cWinApp_get_by_index ( | struct cWinApp * ptr_win_app,
 | int index )

Returns an object with its index.

Parameters:
ptr_win_app | A pointer to the initialized cClip structure
index | Index of the object in cWinApp
Returns:
The object with its index
   #include <cywin.h>
     ...
     struct cButton button1;
     struct cButton button2;
     struct cButton button3;
     struct module_t main_module;
     struct cObject * currentObj;
     int nButtonNumber;
     int i;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button1, "Button text 1", mrOk );
     cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
     ...
     cButton_ctor( &button2, "Button text 2", mrOk );
     cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
     ...
     // It's the same as using the cClip_InsObj( &button3 ) function.
     cButton_ctor( &button3, "Button text 3", mrOk );
     cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
     ...
     // Redraws all objects.
     for ( i=0; i<cWinApp_GetCount( main_module.m_process ); i++)
     {
       cButton_update( cWinApp_get_by_index( main_module.m_process, i) );
     }
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

struct DisplayGraphics * cWinApp_get_display ( void )

Returns the graphics context.

Returns:
The graphics context
   #include <cywin.h>
     ...
     struct Bitmap bmp;
     ...
     // Creates a bitmap from the file "root.ico".
     Bitmap_ctor_Ex1( &bmp, "root.ico" );
     ...
     // Draws bitmap.
     Graphics_draw_bitmap( cWinApp_get_display(), &bmp, 30, 40, BM_NORMAL );
     ...
     Bitmap_dtor( &bmp, LEAVE_MEMORY );
     ...

struct Message * cWinApp_get_message ( | struct cWinApp * ptr_win_app,
 | long timeout,
 | int min,
 | int max )

The calling thread waits until the first message that fits the specified range appears in the queue.
Be careful not to overload the queue. Call Message_delete() when you finish with the message.

Parameters:
ptr_win_app | A pointer to the initialized cWinApp object
timeout | Timeout value (in milliseconds)
min | Retrieves the minimum ID of the message in the queue
max | Retrieves the maximum ID of the message in the queue
Returns:
Pointer to the Message if there is one in the process' queue
   #include <cywin.h>
     ...
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if( ptr_message->msgid == MSG_KEYDOWN )
     {
       if( Message_get_key_param( ptr_message )->scancode == MSG_ESC )
       {
         // Processes key 'Esc'.
       }
     }
   ...
See also:
Message_delete

char * cWinApp_get_name ( struct cWinApp * ptr_win_app )

Returns the message queue's name.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
The message queue's name

bool cWinApp_has_focus ( struct cWinApp * ptr_win_app )

Checks whether the application has the focus.

Parameters:
ptr_win_app A pointer to the cWinApp initialized structure
Returns:
TRUE if the application has the focus
   #include <cywin.h>
   ...
   cWinApp_request_focus( main_module.m_process );
   ...
   if( cWinApp_has_focus( main_module.m_process ) )
   {
     // Draws something.
     ...
   }
   ...

struct DisplayGraphics * cWinApp_init_display ( void )

Obtains the graphics context.

Returns:
A pointer to the DisplayGraphics object
   #include <cywin.h>
     ...
     struct DisplayGraphics* ptr_gfx;
     ...
     // Clears the screen.
     cWinApp_clear_screen();
     ...
     // Draws a filled rectangle.
     ptr_gfx = cWinApp_init_display();
     DisplayGraphics_set_color( ptr_gfx , CLR_BLACK );
     DisplayGraphics_fill_rect( ptr_gfx , 5, 5, 30, 30 );
     DisplayGraphics_show( ptr_gfx );
     ...

bool cWinApp_pause ( | struct cWinApp * ptr_win_app,
 | clock_t timeout )

Pauses execution of the thread.

Parameters:
ptr_win_app | A pointer to the cWinApp initialized structure
timeout | The time span to sleep (in milliseconds)
Returns:
FALSE if the timeout has passed
   #include <cywin.h>
     ...
     play_tone(30);
     cWinApp_pause(main_module.m_process, 200);
     play_tone(-1);
     ...

struct Message * cWinApp_peek_message ( | struct cWinApp * ptr_win_app,
 | bool remove,
 | int min,
 | int max )

Peeks or gets a message from queue.
If 'remove' is TRUE, the message will be removed. This function does not wait for a message to be available, it returns 0 immediately it there are no messages in the specified range. Don't use it unless you really need it.

Parameters:
ptr_win_app | A pointer to the initialized cWinApp object
remove | If TRUE, the message will be removed from the message queue
min | Retrieves the minimum ID of the message in the queue.
max | Retrieves the maximum ID of the message in the queue
Returns:
A pointer to the Message if there is one in the process' queue; otherwise 0
   #include <cywin.h>
     ...
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     // Removes all keyboard messages from the queue.
     while(ptr_message = cWinApp_peek_message( main_module.m_process, 0, MSG_KEYDOWN, MSG_KEYDOWN ))
     {
       Message_delete( ptr_message );
     }
     ...

void cWinApp_put_message ( | struct cWinApp * ptr_win_app,
 | struct Message * ptr_message )

Puts a Message in the Queue.

Parameters:
ptr_win_app | A pointer to the initialized cWinApp object
ptr_message | A pointer to the message to send
Returns:
None
   #include <cywin.h>
   #define MSG_MAKE_TASK MSG_USER + 1
     ...
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_MAKE_TASK );
     if( ptr_message->msgid == MSG_MAKE_TASK )
     {
       cWinApp_pause( main_module.m_process, 250 );
       cWinApp_put_message( main_module.m_process, ptr_message );
     }
     else
     {
       Message_delete( ptr_message );
     }
     ...

struct Process * cWinApp_request_focus ( struct cWinApp * ptr_win_app )

Requests focus for the application.

Parameters:
ptr_win_app A pointer to the cWinApp initialized structure
Returns:
A pointer to a Process object
   #include <cywin.h>
     ...
     cWinApp_request_focus( main_module.m_process );
     ...
     if( cWinApp_has_focus( main_module.m_process ) )
     {
       // Draws something.
       ...
     }
     ...

void cWinApp_update ( struct cWinApp * ptr_win_app )

Updates a cWinApp object.

Parameters:
ptr_win_app A pointer to the initialized cWinApp structure
Returns:
None


Base Structures

Compounds
struct | cClip | This is a base window structure - a clipped box, which may contain other objects
struct | cEngine | Provides timely graphical output
struct | cObject | Represents a simple graphic object, and implements base message-delivery and command-processing functions

Detailed Description

The most basic structures (cObject, cClip, etc.) that serve as a base for the rest of this group, save the AppGeneric and the cWinApp structures. Please pay special attention to the cEngine structure that provides a couple of quite useful services (also, note that there exists a single, unique instance of such an object in the system).


cClip Struct Reference

Inheritance diagram for cClip

Collaboration diagram for cClip:

Public Types
enum tScrolls {
sNone = 0,
sUp = 1,
sDown = 2,
sUpDown = 3
}

Public Methods
void | cClip_AddObj (struct cClip *, struct cObject *, int, int)
void | cClip_InsObj (struct cClip *, struct cObject *, int, int, int)
void | cClip_RemObj (struct cClip *, struct cObject *)
bool | cClip_SelectFirst (struct cClip *)
bool | cClip_SelectPrev (struct cClip *, bool)
bool | cClip_SelectNext (struct cClip *, bool)
void | cClip_Scroll (struct cClip *ptr_clip, struct rect_t *rectangle)
void | cClip_Scroll_Ex (struct cClip *ptr_clip, int x, int y)
void | cClip_SendScroll (struct cClip *ptr_clip)
int | cClip_GetShifty (struct cClip *ptr_clip)
int | cClip_GetShiftx (struct cClip *ptr_clip)
int | cClip_GetCount (struct cClip *ptr_clip)
struct cObject* | cClip_get_by_index (struct cClip *, int)
int | cClip_FindObj (struct cClip *, struct cObject *)
struct cObject* | cClip_GetSelectedObject (struct cClip *ptr_clip)
bool | cClip_proc (struct cClip *ptr_clip, struct Message *ptr_message)
void | cClip_Disconnect (struct cClip *ptr_clip)
bool | cClip_Select (struct cClip *ptr_clip)
void | cClip_update (struct cClip *ptr_clip)
struct cClip* | cClip_GetParent (struct cClip *ptr_clip)
void | cClip_Hide (struct cClip *ptr_clip)
void | cClip_Show (struct cObject *ptr_clip)
void | cClip_Disable (struct Clip *ptr_clip)
void | cClip_Enable (struct cObject *ptr_clip)

Detailed Description

This is a base window structure - a clipped box, which may contain other objects. cClip implements base message-delivery and command-processing functions. It supports scrolling, painting child objects, and so on. You must the initialize structure before use and release object resources after use.

See also:
Base Structures

Member Enumeration Documentation

enum tScrolls

Scroll mode.

Enumeration values:
sNone | no scrolling available.
sUp | enable scrolling up.
sDown | enable scrolling down.
sUpDown | enable scrolling both up and down.

Member Function Documentation

void cClip_AddObj ( | struct cClip * ptr_clip,
 | struct cObject * ptr_object,
 | int x,
 | int y )

Adds the object 'obj' to the cClip in position (x,y).

Parameters:
ptr_clip | A pointer to the initialized cClip structure
ptr_object | A pointer to the initialized cObject structure
x | The x-coordinate of the new object.
y | The y-coordinate of the new object.
Returns:
None
       #include <cywin.h>
       ...
       struct cButton button;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button, "Button text", mrOk );
       // Puts the 'button' object on the Cybiko screen.
       // It's the same as using the cClip_AddObj( &button ) function.
       cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

void cClip_Disable ( struct Clip * ptr_clip )

Disables the cClip object so that it cannot be selected.

Parameters:
ptr_clip A pointer to the initialized cClip structure
Returns:
None

void cClip_Disconnect (

struct cClip * ptr_clip )

Disconnects the cClip from its parent object.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 None

void cClip_Enable (

struct cObject * ptr_clip )

Enables the cClip object - so that it may be selected.

Parameters:

ptr_clip

 is A pointer to the initialized cClip structure

Returns:

 None

int cClip_FindObj ( | struct cClip * ptr_clip,
 | struct cObject * ptr_object )

Returns the child object's index in the cClip.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

ptr_object
   |
 A pointer to the needed cObject

Returns:

 Object index; -1 if the index cannot be found
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       struct cObject * currentObj;
       int    nButtonNumber;
       int    i;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       // Finds the object.
       if ( cClip_FindObj( main_module.m_process, &button2 ) != -1 )
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

int cClip_GetCount (

struct cClip * ptr_clip )

Returns the count of child objects.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 Child objects count
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       int    nButtonNumber;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       // nButtonNumber will be equal to 3.
       nButtonNumber = cClip_GetCount( main_module.m_process );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

struct cClip * cClip_GetParent (

struct cClip * ptr_clip )

Returns a pointer to the parent object's cClip.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 A pointer to the parent object's cClip

struct cObject * cClip_GetSelectedObject (

struct cClip * ptr_clip )

Returns the currently selected object in the cClip.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 The currently selected object in the cClip
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       struct cObject * selectedObj;
       int    nButtonNumber;
       int    i;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       cObject_Select( &button2 );
       ...
       // Redraws selected objects.
       cButton_update( cClip_GetSelectedObject( main_module.m_process );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

int cClip_GetShiftx (

struct cClip * ptr_clip )

Returns the 'x' coordinate shift (as a result of scrolling).

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 'x' coordinate shift
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       int    nShift_X;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       cBitmap_ctor( &cbmp, &bmp );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
       ...
       // Scrolls the bitmap to the visible area.
       cClip_Scroll_Ex( main_module.m_process, -160, -240 );
       cClip_SendScroll( main_module.m_process );
       // nShift_X will be equal to -160.
       nShift_X = cClip_GetShiftx( main_module.m_process );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );

See also:

 cClip_GetShifty.

int cClip_GetShifty (

struct cClip * ptr_clip )

Returns the 'y' coordinate shift (as a result of scrolling).

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 'y' coordinate shift
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       int    nShift_Y;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       cBitmap_ctor( &cbmp, &bmp );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
       ...
       // Scrolls the bitmap to the visible area.
       cClip_Scroll_Ex( main_module.m_process, -160, -240 );
       cClip_SendScroll( main_module.m_process );
       // nShift_Y will be equal to -240.
       nShift_Y = cClip_GetShifty( main_module.m_process );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );

See also:

 cClip_GetShiftx.

void cClip_Hide (

struct cClip * ptr_clip )

Hides the cClip object.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 None

void cClip_InsObj ( | struct cClip * ptr_clip,
 | struct cObject * ptr_object,
 | int x,
 | int y,
 | int index )

Adds the object 'obj' to the cClip in position (x,y), with a z-position index (maximal index is on the top).

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

ptr_object
   |
 A pointer to initialized cObject structure

x
   |
 The x-coordinate of the new object

y
   |
 The y-coordinate of the new object

index
   |
 The z-position of the new object

Returns:

 None
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

void cClip_RemObj ( | struct cClip * ptr_clip,
 | struct cObject * ptr_object )

Removes the object from cClip.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

ptr_object
   |
 A pointer to the initialized cObject structure

Returns:

 None
       #include <cywin.h>
       ...
       struct cButton button;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button, "Button text", mrOk );
       // Puts the 'button' object on the Cybiko screen.
       // It's the same as using the cClip_AddObj( &button ) function.
       cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
       ...
       // It's the same as using the cClip_RemObj( &button ) function.
       cClip_RemObj( main_module.m_process, &button );
       cButton_dtor( &button, LEAVE_MEMORY );

void cClip_Scroll ( | struct cClip * ptr_clip,
 | struct rect_t * rectangle )

Scrolls the cClip to make a specified rectangle visible.
Provides minimal scrolling.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

rectangle
   |
 A pointer to the initialized rect_t structure

Returns:

 None
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       struct rect_t   rect;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       cBitmap_ctor( &cbmp, &bmp );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
       ...
       rect_set( &rect, 160, 240, bmp.h, bmp.w );
       // Scrolls the bitmap to the visible area.
       cClip_Scroll( main_module.m_process, &rect );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cClip_Scroll_Ex ( | struct cClip * ptr_clip,
 | int x,
 | int y )

Scrolls the cClip by ( x, y ), but does not exceed the child's boundaries.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

x
   |
 "x" coordinate shift

y
   |
 "y" coordinate shift

Returns:

 None
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       cBitmap_ctor( &cbmp, &bmp );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
       ...
       // Scrolls the bitmap to the visible area.
       cClip_Scroll_Ex( main_module.m_process, -160, -240 );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );

bool cClip_Select (

struct cClip * ptr_clip )

Selects the cClip object.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 TRUE if the object was selected

bool cClip_SelectFirst (

struct cClip * ptr_clip )

Selects the first object in the cClip.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 FALSE if the operation failed
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       // Selects the first button.
       cClip_SelectFirst( main_module.m_process );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

bool cClip_SelectNext ( | struct cClip * ptr_clip,
 | bool round )

Selects the next object in the cClip.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

round
   |
 TRUE if you need to select the last object after selecting the first

Returns:

 FALSE if the operation failed
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       // Selects the first button.
       cClip_SelectFirst( main_module.m_process );
       ...
       // Selects the next button.
       cClip_SelectNext( main_module.m_process, TRUE );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

bool cClip_SelectPrev ( | struct cClip * ptr_clip,
 | bool round )

Selects the previous object in the cClip.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

round
   |
 TRUE if you need to select the last object after selecting the first

Returns:

 FALSE if the operation failed
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       // Selects the first button.
       cClip_SelectFirst( main_module.m_process );
       ...
       // Selects the previous button.
       cClip_SelectPrev( main_module.m_process, TRUE );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

void cClip_SendScroll (

struct cClip * ptr_clip )

Forces this object to redraw its scrolling arrows.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 None
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       cBitmap_ctor( &cbmp, &bmp );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 160, 240 );
       ...
       // Scrolls the bitmap to the visible area.
       cClip_Scroll_Ex( main_module.m_process, -160, -240 );
       cClip_SendScroll( main_module.m_process );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cClip_Show (

struct cObject * ptr_clip )

Shows the cClip object.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 None

struct cObject * cClip_get_by_index ( | struct cClip * ptr_clip,
 | int index )

Returns an object with its index.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

index
   |
 The index of the object in cClip

Returns:

 If the index is valid, a pointer to the cObject under the specified index; else NULL.
       #include <cywin.h>
       ...
       struct cButton button1;
       struct cButton button2;
       struct cButton button3;
       struct module_t main_module;
       struct cObject * currentObj;
       int    nButtonNumber;
       int    i;
       ...
       init_module( &main_module );
       ...
       cButton_ctor( &button1, "Button text 1", mrOk );
       cWinApp_AddObj( main_module.m_process, &button1, 20, 50 );
       ...
       cButton_ctor( &button2, "Button text 2", mrOk );
       cWinApp_InsObj( main_module.m_process, &button2, 20, 50, 1 );
       ...
       // It's the same as using the cClip_InsObj( &button3 ) function.
       cButton_ctor( &button3, "Button text 3", mrOk );
       cWinApp_InsObj( main_module.m_process, &button3, 20, 50, 2 );
       ...
       // Redraws all objects.
       for ( i=0; i<cClip_GetCount( main_module.m_process ); i++)
       {
         cButton_update( cClip_get_by_index( main_module.m_process, i) );
       }
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

bool cClip_proc ( | struct cClip * ptr_clip,
 | struct Message * ptr_message )

Message-processing function.

Parameters:

ptr_clip
   |
 A pointer to the initialized cClip structure

ptr_message
   |
 A pointer to the processed message

Returns:

 TRUE if the message was processed
  #include <cywin.h>
  ...
  struct cClip* ptr_messages_clip;
  struct Message* ptr_message;
  ...
  case KEY_DOWN:
    cClip_proc( ptr_chat_form->ptr_messages_clip, ptr_message );
    return TRUE;
  ...

void cClip_update (

struct cClip * ptr_clip )

Updates a cClip object.

Parameters:

ptr_clip

 A pointer to the initialized cClip structure

Returns:

 None


cEngine Struct Reference

Inheritance diagram for cEngine

Collaboration diagram for cEngine:

Public Methods
int | cEngine_Lock (struct cEngine *ptr_engine)
int | cEngine_Unlock (struct cEngine *ptr_engine)

Public Attributes
struct cEngine | Screen

Detailed Description

Provides timely graphical output. The screen shows only one cEngine object.

See also:
Base Structures

Member Function Documentation

int cEngine_Lock ( struct cEngine * ptr_engine )

Locks a cEngine object.
Updates are not performed while it is locked. After each cEngine_Lock function, the cEngine_Unlock function must be called somewhere later in the program.

Parameters:
ptr_engine A pointer to the initialized cEngine object
Returns:
Lock counter
       #include <cywin.h>
       ...
       cEngine_Lock( &Screen );
       ...
       //  Performs time-consuming drawing.
       ...
       cEngine_Unlock(  &Screen );
       ...
See also:
cEngine_Unlock.

int cEngine_Unlock ( struct cEngine * ptr_engine )

Unlocks a cEngine object.
The cEngine_Unlock function must be called once for every time the cEngine_Lock function was called.

Parameters:
ptr_engine A pointer to the initialized cEngine object
Returns:
Lock counter. If it is greater than 0, cEngine is still locked
       #include <cywin.h>
       ...
       cEngine_Lock( &Screen );
       //  Performs time-consuming drawing.
       ...
       cEngine_Unlock(  &Screen );
       ...
See also:
cEngine_Lock.

Member Data Documentation

struct cEngine Screen

Global CyWin cEngine object.

       #include <cywin.h>
       ...
       cEngine_Lock( &Screen );
       ...
       //  Performs time-consuming drawing.
       ...
       cEngine_Unlock(  &Screen );
       ...


cObject Struct Reference

Inheritance diagram for cObject

Detailed Description

The CyOS base object. Represents a simple graphic object and implements base message-delivery and command-processing functions.

See also:
Base Structures


Forms & Containers

Enumerations
enum tMResults {
mrNone,
mrOk,
mrYes,
mrNo,
mrDraw,
mrChat,
mrQuit,
mrNew = 6,
mrUpload,
mrRename,
mrDelete,
mrView,
mrPlay,
mrRestart,
mrSet,
mrLater,
mrCancel,
mrMessage,
mrUser = 32
}
enum tDialogStyle {
mbNone = 0x0,
mbOk = 0x1,
mbYes = 0x2,
mbNo = 0x4,
mbDraw = 0x8,
mbChat = 0x10,
mbQuit = 0x20,
mbNew = 0x20,
mbUpload = 0x40,
mbRename = 0x80,
mbDelete = 0x100,
mbView = 0x200,
mbPlay = 0x400,
mbRestart = 0x800,
mbSet = 0x1000,
mbLater = 0x2000,
mbCancel = 0x4000,
mbEdit = 0x10000,
mbPasswd = 0x20000,
mbNoEsc = 0x40000,
mbLeft = 0x80000,
mbNoShutup = 0x100000,
mbReverseOrder = 0x200000,
mbsDefault = 0x0,
mbsNone = 0x0,
mbs0 = 0x0,
mbs1 = 0x400000,
mbs2 = 0x800000,
mbs3 = 0xC00000,
mbs4 = 0x1000000,
mbs5 = 0x1400000,
mbs6 = 0x1800000,
mbs7 = 0x1C00000,
mbsMask = 0x1C00000,
mbsAbout = mbs6,
mbsDraw = mbs4,
mbsEsc = mbs5,
mbsLinkOff = mbs1,
mbsNoDraw = mbs7,
mbsWelcome = mbs2
}

Compounds
struct | cCustomForm | This is a structure of the main form
struct | cDialog | The structure for common dialogs
struct | cFrameForm | This structure creates a full-screen, framed window

Detailed Description

Forms (cCustomForm, cFrameForm) are structures that can be used as containers that 'host' other elements, such as controls (see below). Please note that cDialog is a ready-to-use thing, you just have to provide its constructor with flags (there are about 40 bit masks for your convenience, so the whole thing is highly configurable).

Enumeration Type Documentation

enum tDialogStyle

Dialog styles.
Constants with value 1..0x8000 are buttons. Other constants are special style constants.

Enumeration values:
mbNone | no buttons.
mbOk | "OK" button.
mbYes | "YES" button.
mbNo | "NO" button.
mbDraw | "DRAW" button.
mbChat | "CHAT" button.
mbQuit | "QUIT" button.
mbNew | "NEW" button.
mbUpload | "UPLOAD" button.
mbRename | "RENAME" button.
mbDelete | "DELETE" button.
mbView | "VIEW" button.
mbPlay | "PLAY" button.
mbRestart | "RESTART" button.
mbSet | "SET" button.
mbLater | "LATER" button.
mbCancel | "CANCEL" button.
mbEdit | edit string attached to dialog.
mbPasswd | dialog's edit is in password mode (all symbols are viewed as '*').
mbNoEsc | do not close dialog when <Esc> button is pressed. (normally, dialog will close with mrCancel ModalResult).
mbLeft | set dialog text flush left flush left (normally, dialog text is centered).
mbNoShutup | dialog should ignore "msg_shutup" message. Used in "program close" dialogs.
mbReverseOrder | reverse the order of the buttons in the dialog (for example, <Cancel> moves to the left of <OK>).
mbsDefault | play default music when the dialog is shown.
mbsNone | don't play any music is playing when the dialog is shows.
mbs0 | play Music 1 when the dialog is shown.
mbs1 | play Music 2 when the dialog is shown.
mbs2 | play Music 3 when the dialog is shown.
mbs3 | play Music 4 when the dialog is shown.
mbs4 | play Music 5 when the dialog is shown.
mbs5 | play Music 6 when the dialog is shown.
mbs6 | play Music 7 when the dialog is shown.
mbs7 | play Music 8 when the dialog is shown.
mbsMask | shift the music fields.
mbsAbout | The same as mbs6.
mbsDraw | The same as mbs4.
mbsEsc | The same as mbs5.
mbsLinkOff | The same as mbs1.
mbsNoDraw | The same as mbs7.
mbsWelcome | The same as mbs2.

enum tMResults

Predefined results that may be returned from modal forms.
You can use your own results too.

Enumeration values:
mrNone | no result available.
mrOk | "OK" button pressed.
mrYes | "YES" button pressed.
mrNo | "NO" button pressed.
mrDraw | "DRAW" button pressed.
mrChat | "CHAT" button pressed.
mrQuit | "QUIT" button pressed.
mrNew | "NEW" button pressed.
mrUpload | "UPLOAD" button pressed.
mrRename | "RENAME" button pressed.
mrDelete | "DELETE" button pressed.
mrView | "VIEW" button pressed.
mrPlay | "PLAY" button pressed.
mrRestart | "RESTART" button pressed.
mrSet | "SET" button pressed.
mrLater | "LATER" button pressed.
mrCancel | "CANCEL" button pressed.
mrMessage | Message received.
mrUser | beginning of the user's definitions.


cCustomForm Struct Reference

Inheritance diagram for cCustomForm

Collaboration diagram for cCustomForm:

Public Methods
struct cCustomForm* | cCustomForm_ctor (struct cCustomForm *ptr_custom_form, struct rect_t *rect, char *name, bool round, struct cWinApp *ptr_win_app)
void | cCustomForm_dtor (struct cCustomForm *ptr_custom_form, int memory_flag)
int | cCustomForm_ShowModal (struct cCustomForm *ptr_custom_form)
bool | cCustomForm_proc (struct cCustomForm *ptr_custom_form, struct Message *ptr_message)
void | cCustomForm_Disconnect (struct cCustomForm *ptr_custom_form)
bool | cCustomForm_Select (struct cCustomForm *ptr_custom_form)
void | cCustomForm_update (struct cCustomForm *ptr_custom_form)
struct cClip* | cCustomForm_GetParent (struct cCustomForm *ptr_custom_form)
void | cCustomForm_Hide (struct cCustomForm *ptr_custom_form)
void | cCustomForm_Show (struct cCustomForm *ptr_custom_form)
void | cCustomForm_Disable (struct cCustomForm *ptr_custom_form)
void | cCustomForm_Enable (struct cCustomForm *ptr_custom_form)
void | cCustomForm_AddObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object, int x, int y)
void | cCustomForm_InsObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object, int x, int y, int index)
void | cCustomForm_RemObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object)
bool | cCustomForm_SelectFirst (struct cCustomForm *ptr_custom_form)
bool | cCustomForm_SelectPrev (struct cCustomForm *ptr_custom_form, bool round)
bool | cCustomForm_SelectNext (struct cCustomForm *ptr_custom_form, bool round)
void | cCustomForm_Scroll (struct cCustomForm *ptr_custom_form, struct rect_t *rectangle)
void | cCustomForm_Scroll_Ex (struct cCustomForm *ptr_custom_form, int x, int y)
void | cCustomForm_SendScroll (struct cCustomForm *ptr_custom_form)
int | cCustomForm_GetShifty (struct cCustomForm *ptr_custom_form)
int | cCustomForm_GetShiftx (struct cCustomForm *ptr_custom_form)
int | cCustomForm_GetCount (struct cCustomForm *ptr_custom_form)
struct cObject* | cCustomForm_get_by_index (struct cCustomForm *ptr_custom_form, int index)
int | cCustomForm_FindObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object)
struct cObject* | cCustomForm_GetSelectedObject (struct cCustomForm *ptr_custom_form)

Public Attributes
char | FormNameString [30]
char | Type
struct cWinApp* | CurrApplication
struct cClip* | ClientArea
int | ModalResult
int | HelpContext

Detailed Description

This is the main form structure, used to produce full-screen rectangle and rounded-rectangle windows (forms). Forms are useful for creating non-game applications. These applications usually consist of one or more hierarchically organized screens or windows, and the user moves between them in accordance with its hierarchy.

To achieve this using forms, you should simply derive one cCustomForm structure for every window you need. Then in your application, create your main window's object and call its cCustomForm_ShowModal method. If you need to show another window somewhere, create the object of the form structure you need and fill the form fields. Then call its ShowModal method, read the save form data, and delete the form.

You can also create non-modal windows, if you need to. After creating a form, you can view it (see cCustomForm_Show). When a message comes in, call the form's cCustomForm_Proc function to process it. The key is one form per screen or window.

You must call the cCustomForm_ctor function before use and the cCustomForm_dtor function after use.

See also:
Forms & Containers

Member Function Documentation

void cCustomForm_AddObj ( | struct cCustomForm * ptr_custom_form,
 | struct cObject * ptr_object,
 | int x,
 | int y )

Adds an object to the cCustomForm in position ( x, y ).

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
ptr_object | A pointer to the initialized cObject structure
x | The x-coordinate of the new object
y | The y-coordinate of the new object
Returns:
None
   #include <cywin.h>
   ...
   ptr_menu_form = (struct cCustomForm*) malloc( sizeof *ptr_menu_form );
   ...
   form_rect.x = 40;
   form_rect.y = 20;
   form_rect.w = 86;
   form_rect.h = 60;
   ...
   cCustomForm_ctor( ptr_menu_form, &form_rect, "Main Menu",
     TRUE, ptr_win_app );
   ...
   ptr_menu_form->HelpContext = 0;
   ptr_menu_form->ModalResult = mrNone;
   ...
   // Adds the menu to the menu form
   cCustomForm_AddObj( ptr_menu_form, ptr_menu, 0, 0 );
   ...
   cCustomForm_Hide( ptr_menu_form );
   ...
   // Creates text
   ptr_text = (struct cText*) malloc( sizeof *ptr_text );
   ...
   cText_ctor( ptr_text, "Press <Enter>", cool_normal_font, CLR_BLACK );
   ...
   // Adds the text to the main form
   cFrameForm_AddObj( ptr_form, ptr_text, 42, 35 );
   ...

void cCustomForm_Disable ( struct cCustomForm * ptr_custom_form )

Disables the cCustomForm object so that it cannot be selected.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
None
See also:
cCustomForm_Enable.

void cCustomForm_Disconnect ( struct cCustomForm * ptr_custom_form )

Disconnects a cCustomForm from its parent object.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
None

void cCustomForm_Enable ( struct cCustomForm * ptr_custom_form )

Enables a cCustomForm object so that it may be selected.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
None
See also:
cCustomForm_Disable.

int cCustomForm_FindObj ( | struct cCustomForm * ptr_custom_form,
 | struct cObject * ptr_object )

Returns the child object index in a cCustomForm (or -1 if the object was not found).

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
ptr_object | A pointer to the initialized cObject structure
Returns:
The child object index in cCustomForm (or -1 if the object was not found)

int cCustomForm_GetCount ( struct cCustomForm * ptr_custom_form )

Returns the count of child objects.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
Child objects count

struct cClip * cCustomForm_GetParent ( struct cCustomForm * ptr_custom_form )

Returns a pointer to the parent object.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
A pointer to the parent object

struct cObject * cCustomForm_GetSelectedObject ( struct cCustomForm * ptr_custom_form )

Returns the currently selected object.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
The currently selected object

int cCustomForm_GetShiftx ( struct cCustomForm * ptr_custom_form )

Returns the 'x' coordinate shift (as a result of scrolling).

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
'x' coordinate shift (as a result of scrolling)

int cCustomForm_GetShifty ( struct cCustomForm * ptr_custom_form )

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
'y' coordinate shift (at result of scrolling)

void cCustomForm_Hide ( struct cCustomForm * ptr_custom_form )

Hides a cCustomForm object.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
None
   #include <cywin.h>
   ...
   ptr_menu_form = (struct cCustomForm*) malloc( sizeof *ptr_menu_form );
   ...
   form_rect.x = 40;
   form_rect.y = 20;
   form_rect.w = 86;
   form_rect.h = 60;
   ...
   cCustomForm_ctor( ptr_menu_form, &form_rect, "Main Menu",
     TRUE, ptr_win_app );
   ...
   ptr_menu_form->HelpContext = 0;
   ptr_menu_form->ModalResult = mrNone;
   ...
   // Adds the menu to the menu form
   cCustomForm_AddObj( ptr_menu_form, ptr_menu, 0, 0 );
   ...
   cCustomForm_Hide( ptr_menu_form );
   ...
   // Creates text
   ptr_text = (struct cText*) malloc( sizeof *ptr_text );
   ...
   cText_ctor( ptr_text, "Press <Enter>", cool_normal_font, CLR_BLACK );
   ...
   // Adds the text to the main form
   cFrameForm_AddObj( ptr_form, ptr_text, 42, 35 );
   ...
See also:
cCustomForm_Show.

void cCustomForm_InsObj ( | struct cCustomForm * ptr_custom_form,
 | struct cObject * ptr_object,
 | int x,
 | int y,
 | int index )

Adds an object to the cCustomForm in position ( x, y ) with a z-position 'index' (maximal index is on the top).

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
ptr_object | A pointer to the initialized cObject structure
x | The x-coordinate of the new object
y | The y-coordinate of the new object
index | The z-position of the new object
Returns:
None

void cCustomForm_RemObj ( | struct cCustomForm * ptr_custom_form,
 | struct cObject * ptr_object )

Removes an object from a cCustomForm.

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
ptr_object | A pointer to the initialized cObject structure
Returns:
None

void cCustomForm_Scroll ( | struct cCustomForm * ptr_custom_form,
 | struct rect_t * rectangle )

Scrolls a cCustomForm to make a rectangle visible.
Provides minimal scrolling.

Parameters:
ptr_custom_form | A pointer to initialized cCustomForm structure
rectangle | A pointer to the initialized rect_t structure
Returns:
None
See also:
cCustomForm_Scroll_Ex.

void cCustomForm_Scroll_Ex ( | struct cCustomForm * ptr_custom_form,
 | int x,
 | int y )

Scrolls a cCustomForm by ( x, y ), but will not exceed the child's boundaries.

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
x | "x" coordinate shift
y | "y" coordinate shift
Returns:
None
See also:
cCustomForm_Scroll.

bool cCustomForm_Select ( struct cCustomForm * ptr_custom_form )

Selects a cCustomForm object.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
TRUE if the object was selected.

bool cCustomForm_SelectFirst ( struct cCustomForm * ptr_custom_form )

Selects the first object in the cCustomForm.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
FALSE if the function failed

bool cCustomForm_SelectNext ( | struct cCustomForm * ptr_custom_form,
 | bool round )

Selects the next object in the cCustomForm.

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
round | TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed

bool cCustomForm_SelectPrev ( | struct cCustomForm * ptr_custom_form,
 | bool round )

Selects the previous object in the cCustomForm.

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
round | TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed

void cCustomForm_SendScroll ( struct cCustomForm * ptr_custom_form )

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
None

void cCustomForm_Show ( struct cCustomForm * ptr_custom_form )

Shows a cCustomForm object.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
None
   #include <cywin.h>
   ...
   int cMainMenu_ShowModal( struct cCustomForm* ptr_form )
   {
    cCustomForm_Show( ptr_form );
    ...
    ptr_form->ModalResult = mrNone;
    ...
    while( ptr_form->ModalResult == mrNone )
    {
      struct Message* ptr_message =
        cWinApp_get_message( ptr_form->CurrApplication, 0, 1, MSG_USER );
      ...
      cMainMenu_proc( ptr_form, ptr_message );
      ...
      cCustomForm_update( ptr_form );
      ...
      Message_delete( ptr_message );
    }
    return ptr_form->ModalResult;
   }
   ...
See also:
cCustomForm_Hide.

int cCustomForm_ShowModal ( struct cCustomForm * ptr_custom_form )

Shows a form in modal mode.
This function shows the form and enters it to the message loop. The loop continues until anyone ModalResult variable is set to a non-zero value, or until a MSG_QUIT or MSG_SHUTUP messages is received. If these messages are received, the function reposts them to the application and leaves the message loop. This is how all forms will close when the applications ends.

Parameters:
ptr_custom_form A pointer to a cCustomForm object
Returns:
tMResults value. mrNone(Zero) if MSG_QUIT or MSG_SHUTUP messages initiates leaving the loop See tMResults enum for predefined results
   #include <cywin.h>
     ...
     struct cCustomForm custom_form;
     struct rect_t rect;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
     cCustomForm_ShowModal( &custom_form );
     ...
     cCustomForm_dtor( &custom_form, LEAVE_MEMORY );
See also:
cCustomForm_ctor , MSG_QUIT , MSG_SHUTUP

struct cCustomForm * cCustomForm_ctor ( | struct cCustomForm * ptr_custom_form,
 | struct rect_t * rect,
 | char * name,
 | bool round,
 | struct cWinApp * ptr_win_app )

Constructor.
Creates a cCustomForm object.

Parameters:
ptr_custom_form | A pointer to a cCustomForm object
rect | A window rectangle. If you want to create a full-screen form, you must set 'rect' to {-2,-2,164,104}
name | The form header caption. If NULL, the form has no header
round | If TRUE, the form shows a rectangle window with rounded corners; otherwise the form shows a plain rectangular window
ptr_win_app | A pointer to a cWinApp object. If NULL, the form will not be added to any application, so you can't use it in modal mode. Don't call cCustomForm_ShowModal if you set ptr_win_app to NULL. The forms are hidden, when created. To show them, use the cCustomForm_Show() or cCustomForm_ShowModal() functions.
Returns:
A pointer to the initialized cCustomForm object
    #include <cywin.h>
      ...
      struct cCustomForm custom_form;
      struct rect_t rect;
      struct module_t main_module;
      ...
      init_module( &main_module );
      ...
      cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
      cCustomForm_ShowModal( &custom_form );
      ...
      cCustomForm_dtor( &custom_form, LEAVE_MEMORY );

void cCustomForm_dtor ( | struct cCustomForm * ptr_custom_form,
 | int memory_flag )

Deletes a cCustomForm object.

Parameters:
ptr_custom_form | A pointer to a cCustomForm object.
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if the object was static or allocated in stack.
Returns:
None
   #include <cywin.h>
     ...
     struct cCustomForm custom_form;
     struct rect_t rect;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
     cCustomForm_ShowModal( &custom_form );
     ...
     cCustomForm_dtor( &custom_form, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct cObject * cCustomForm_get_by_index ( | struct cCustomForm * ptr_custom_form,
 | int index )

Returns the object index.

Parameters:
ptr_custom_form | A pointer to the initialized cCustomForm structure
Index | of object
Returns:
A pointer to the object

bool cCustomForm_proc ( | struct cCustomForm * ptr_custom_form,
 | struct Message * ptr_message )

The message-processing function.

Parameters:
ptr_custom_form | A pointer to a cCustomForm object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed
   #include <cywin.h>
     ...
     struct cCustomForm custom_form;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
     ...
     // Adding some objects to the custom form.
     ...
     cCustomForm_Show( &custom_form );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       //  If 'Tab' was pressed, the next form's object will receive the focus.
       cCustomForm_proc( &custom_form, ptr_message );
     }
     ...
     cCustomForm_dtor( &custom_form, LEAVE_MEMORY );

void cCustomForm_update ( struct cCustomForm * ptr_custom_form )

Updates a cCustomForm object.

Parameters:
ptr_custom_form A pointer to the initialized cCustomForm structure
Returns:
None
   #include <cywin.h>
   ...
   int cMainMenu_ShowModal( struct cCustomForm* ptr_form )
   {
    cCustomForm_Show( ptr_form );
    ...
    ptr_form->ModalResult = mrNone;
    ...
    while( ptr_form->ModalResult == mrNone )
    {
      struct Message* ptr_message =
        cWinApp_get_message( ptr_form->CurrApplication, 0, 1, MSG_USER );
      ...
      cMainMenu_proc( ptr_form, ptr_message );
      ...
      cCustomForm_update( ptr_form );
      ...
      Message_delete( ptr_message );
     }
     return ptr_form->ModalResult;
   }
   ...

Member Data Documentation

struct cClip * ClientArea

The client area of the form.
All "normal" objects are added to the form's client area, including all free form space, and excluding the header and border.

struct cWinApp * CurrApplication

Parent application.

char FormNameString[30]

Form caption.

int HelpContext

Window help context.
You can set it to a non-zero value in the 0..999 range, and, when the '<?>' key is pressed, the help file named '<your value>.help' will be showed. The default value is zero.

int ModalResult

Result of form or dialog.
Modal forms run while the ModalResult is zero. When you set it to non-zero value, the modal cycle is canceled and ShowModal() returns ModalResult value. There are some predefined values (see tMResults). ModalResult can be set automatically, when you press <Esc> in the form, or when you press the in-form cButton.

char Type

Form type (rect or rounded box).


cDialog Struct Reference

Inheritance diagram for cDialog

Collaboration diagram for cDialog:

Public Methods
struct cDialog* | cDialog_ctor (struct cDialog *ptr_dialog, char *caption, char *text, long style, int edit_size, struct cWinApp *ptr_win_app)
void | cDialog_dtor (struct cDialog *ptr_dialog, int memory_flag)
void | cDialog_GetEditText (struct cDialog *ptr_dialog, char *ptr_buffer)
void | cDialog_SetEditText (struct cDialog *ptr_dialog, char *text)
void | cDialog_PlaySound (long number)
bool | cDialog_proc (struct cDialog *ptr_dialog, struct Message *ptr_message)
int | cDialog_ShowModal (struct cDialog *ptr_dialog)
void | cDialog_Disconnect (struct cDialog *ptr_dialog)
bool | cDialog_Select (struct cDialog *ptr_dialog)
void | cDialog_update (struct cDialog *ptr_dialog)
struct cClip* | cDialog_GetParent (struct cDialog *ptr_dialog)
void | cDialog_Hide (struct cDialog *ptr_dialog)
void | cDialog_Show (struct cDialog *ptr_dialog)
void | cDialog_Disable (struct cDialog *ptr_dialog)
void | cDialog_Enable (struct cDialog *ptr_dialog)
void | cDialog_AddObj (struct cDialog *ptr_dialog, struct cObject *ptr_object, int x, int y)
void | cDialog_InsObj (struct cDialog *ptr_dialog, struct cObject *ptr_object, int x, int y, int index)
void | cDialog_RemObj (struct cClip *ptr_dialog, struct cObject *ptr_object)
bool | cDialog_SelectFirst (struct cDialog *ptr_dialog)
bool | cDialog_SelectPrev (struct cDialog *ptr_dialog, bool round)
bool | cDialog_SelectNext (struct cDialog *ptr_dialog, bool round)
void | cDialog_Scroll (struct cDialog *ptr_dialog, struct rect_t *rectangle)
void | cDialog_Scroll_Ex (struct cDialog *ptr_dialog, int x, int y)
void | cDialog_SendScroll (struct cDialog *ptr_dialog)
int | cDialog_GetShifty (struct cDialog *ptr_dialog)
int | cDialog_GetShiftx (struct cDialog *ptr_dialog)
int | cDialog_GetCount (struct cDialog *ptr_dialog)
struct cObject* | cDialog_get_by_index (struct cDialog *ptr_dialog, int index)
int | cDialog_FindObj (struct cDialog *ptr_dialog, struct cObject *ptr_object)
struct cObject* | cDialog_GetSelectedObject (struct cDialog *ptr_dialog)

Detailed Description

This is a common dialog structure. You can create a various types of dialog windows using the third parameter of the cDialog_ctor function.

Dialog styles are defined by combinations of constants of the "tDialogStyle" enumeration (see the "Enumerations" page). For example, you can create a combination like this: "mbOk | mbCancel | mbEdit". This dialog box contains "Ok" and "Cancel" buttons, plus editing field that has been defined by the "mbEdit" parameter. In this case, both the cButton_GetEditText and cButton_SetEditText functions are enabled.

After creating a dialog box, you can show it (see cDialog_ShowModal), and then when a message comes in, you can process it by calling the cDialog_proc function.

You must call the cDialog_ctor function before use and the cDialog_dtor function after use.

See also:
Forms & Containers , cButton_GetEditText , cButton_SetEditText

Member Function Documentation

void cDialog_AddObj ( | struct cDialog * ptr_dialog,
 | struct cObject * ptr_object,
 | int x,
 | int y )

Adds an object to the cDialog in position (x, y).

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
ptr_object | A pointer to the initialized cObject structure
x | The x-coordinate of the new object
y | The y-coordinate of the new object
Returns:
None

void cDialog_Disable ( struct cDialog * ptr_dialog )

Disables cDialog object so that it cannot be selected.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
None
   #include <cywin.h>
       ...
       struct cDialog dialog;
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       cDialog_ctor( &dialog, NULL, str_Really_exit,
                     mbQuit | mbCancel | mbs1, 0, main_module.m_process );
       ...
       cDialog_Show( &dialog );
       ...
       cDialog_Disable( &dialog );
       ...
       cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Enable.

void cDialog_Disconnect ( struct cDialog * ptr_dialog )

Disconnects the cDialog from its parent object.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
None

void cDialog_Enable ( struct cDialog * ptr_dialog )

Enables the cDialog object so that it may be selected.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
None
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, NULL, str_Really_exit,
                   mbQuit | mbCancel | mbs1, 0, main_module.m_process );
     ...
     cDialog_Show( &dialog );
     ...
     cDialog_Disable( &dialog );
     cDialog_Enable ( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Disable.

int cDialog_FindObj ( | struct cDialog * ptr_dialog,
 | struct cObject * ptr_object )

Returns the child object index in the cDialog (or -1).

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
ptr_object | A pointer to the initialized cObject object
Returns:
Child object index in cDialog (or -1)

int cDialog_GetCount ( struct cDialog * ptr_dialog )

Returns the count of child objects.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
Child objects count

void cDialog_GetEditText ( | struct cDialog * ptr_dialog,
 | char * ptr_buffer )

Copies an edit string from the internal buffer into "ptr_buffer".
You must provide enough space for the buffer.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
ptr_buffer | A pointer to the allocated buffer
Returns:
None
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit, 10, main_module.m_process );
     ...
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_SetEditText.

struct cClip * cDialog_GetParent ( struct cDialog * ptr_dialog )

Returns a pointer to the parent object.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
A pointer to the parent object

struct cObject * cDialog_GetSelectedObject ( struct cDialog * ptr_dialog )

Returns the currently selected object.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
Currently selected object

int cDialog_GetShiftx ( struct cDialog * ptr_dialog )

Returns the x coordinate shift (as a result of scrolling).

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
x coordinate shift (as a result of scrolling)

int cDialog_GetShifty ( struct cDialog * ptr_dialog )

Returns the y coordinate shift (as a result of scrolling).

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
y coordinate shift (as a result of scrolling)

void cDialog_Hide ( struct cDialog * ptr_dialog )

Hides the cDialog object.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
None
   #include <cywin.h>
    ...
    struct cDialog dialog;
    struct module_t main_module;
    struct Message* ptr_message;
    ...
    init_module( &main_module );
    ...
    cDialog_ctor( &dialog, NULL, str_Really_exit,
                    mbQuit | mbCancel | mbs1, 0, main_module.m_process );
    ...
    cDialog_Show( &dialog );
    ...
    cDialog_Hide( &dialog );
    ...
    cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Show.

void cDialog_InsObj ( | struct cDialog * ptr_dialog,
 | struct cObject * ptr_object,
 | int x,
 | int y,
 | int index )

Adds an object to the cDialog in position (x, y) with a z-position index (maximal index is on the top).

Parameters:
ptr_dialog | A pointer to the initialized cDialog object.
ptr_object | A pointer to the initialized cObject structure
x | The x-coordinate of the new object
y | The y-coordinate of the new object
index | The z-position of the new object
Returns:
None

void cDialog_PlaySound ( long number )

Plays the standard dialog sound.

Parameters:
number The sound's number (from mbs0 to mbs6)
Returns:
None
   #include <cywin.h>
   {
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit | mbs1, 10, main_module.m_process );
     ...
     cDialog_SetEditText( &dialog, "Bill Gates" );
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
       if( !strlen( sz_name ) )
       {
         cDialog_PlaySound( mbs2 );
       }
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
   }

void cDialog_RemObj ( | struct cClip * ptr_dialog,
 | struct cObject * ptr_object )

Removes an object from the cDialog.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object.
ptr_object | A pointer to the initialized cObject structure
Returns:
None

void cDialog_Scroll ( | struct cDialog * ptr_dialog,
 | struct rect_t * rectangle )

Scrolls cDialog to make rectangle visible.
Provides minimal scrolling.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object.
rectangle | A pointer to the initialized rect_t object.
Returns:
None
See also:
cDialog_Scroll_Ex.

void cDialog_Scroll_Ex ( | struct cDialog * ptr_dialog,
 | int x,
 | int y )

Scrolls a cDialog by ( x, y ), but cannot exceed the child's boundaries.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object.
x | "x" coordinate shift
y | "y" coordinate shift
Returns:
None
See also:
cDialog_Scroll.

bool cDialog_Select ( struct cDialog * ptr_dialog )

Selects a cDialog object.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
TRUE if object was selected

bool cDialog_SelectFirst ( struct cDialog * ptr_dialog )

Selects the first object in the cDialog.

Parameters:
ptr_dialog A pointer to the initialized cDialog object.
Returns:
FALSE if the function failed.

bool cDialog_SelectNext ( | struct cDialog * ptr_dialog,
 | bool round )

Selects the next object in the cDialog.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
round | TRUE if you need to select the last object after the first
Returns:
FALSE if the function failed.

bool cDialog_SelectPrev ( | struct cDialog * ptr_dialog,
 | bool round )

Selects the previous object in the cDialog.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
round | TRUE if you need to select the last object after the first
Returns:
FALSE if the function failed

void cDialog_SendScroll ( struct cDialog * ptr_dialog )

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
None

void cDialog_SetEditText ( | struct cDialog * ptr_dialog,
 | char * text )

Sets an initial string in an edit line.
Does not work if the mbEdit style is not defined.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
text | The text to show
Returns:
None
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit, 10, main_module.m_process );
     ...
     cDialog_SetEditText( &dialog, "Bill Gates" );
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_GetEditText.

void cDialog_Show ( struct cDialog * ptr_dialog )

Shows a cDialog object.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
None
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, NULL, str_Really_exit,
                     mbQuit | mbCancel | mbs1, 0, main_module.m_process );
     ...
     cDialog_Show( &dialog );
     ...
     cDialog_Hide( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Hide.

int cDialog_ShowModal ( struct cDialog * ptr_dialog )

Shows a cDialog in modal mode.
This function shows the cDialog and enters it into the message loop. The loop continues until any one ModalResult variable is set a to non-zero value, or until a MSG_QUIT or MSG_SHUTUP message is received. If these messages are received, the function reposts them to the application and leaves the message loop. This is how all forms will close when the application ends.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
tMResults value. mrNone(Zero) if MSG_QUIT or MSG_SHUTUP messages initiates leaving the loop. There are some predefined results
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit, 10, main_module.m_process );
     ...
     cDialog_SetEditText( &dialog, "Bill Gates" );
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
tMResults , MSG_QUIT , MSG_SHUTUP.

struct cDialog * cDialog_ctor ( | struct cDialog * ptr_dialog,
 | char * caption,
 | char * text,
 | long style,
 | int edit_size,
 | struct cWinApp * ptr_win_app )

Initializes a cDialog object.

Parameters:
ptr_dialog | A pointer to a cDialog object
caption | Dialog caption
text | Dialog text
style | Dialog style. The style is a combination of "tDialogStyle" constants
edit_size | Edit string size (in symbols). If mbEdit not defined in the style, this parameter is not used
ptr_win_app | A pointer to the structure of the current cywin application
Returns:
A pointer to the initialized cDialog object
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Caption", "Dialog Text",
                     mbYes | mbNo, 0, main_module.m_process );
     ...
     cDialog_ShowModal( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );

void cDialog_dtor ( | struct cDialog * ptr_dialog,
 | int memory_flag )

Destructor.
Deletes the cDialog object.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY. Use LEAVE_MEMORY if object was static or allocated in stack use LEAVE_MEMORY.
Returns:
None
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Caption", "Dialog Text",
                     mbYes | mbNo, 0, main_module.m_process );
     ...
     cDialog_ShowModal( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct cObject * cDialog_get_by_index ( | struct cDialog * ptr_dialog,
 | int index )

Returns the object's index (or NULL).

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
index | The object's index
Returns:
Object's index (or NULL)

bool cDialog_proc ( | struct cDialog * ptr_dialog,
 | struct Message * ptr_message )

Message-processing function.

Parameters:
ptr_dialog | A pointer to the initialized cDialog object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, NULL, str_Really_exit,
                     mbQuit | mbCancel | mbs1, 0, main_module.m_process );
     ...
     cDialog_Show( &dialog );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if( cDialog_proc( &dialog, ptr_message ) && dialog.ModalResult != mrNone )
     {
       if( dialog.ModalResult == mrQuit )
       {
         ...
       }
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );

void cDialog_update ( struct cDialog * ptr_dialog )

Updates a cDialog object.

Parameters:
ptr_dialog A pointer to the initialized cDialog object
Returns:
None


cFrameForm Struct Reference

Inheritance diagram for cFrameForm

Collaboration diagram for cFrameForm:

Public Methods
struct cFrameForm* | cFrameForm_ctor (struct cFrameForm *ptr_frame_form, char *text, struct cWinApp *ptr_win_app)
void | cFrameForm_dtor (struct cFrameForm *ptr_frame_form)
int | cFrameForm_ShowModal (struct cFrameForm *ptr_frame_form)
bool | cFrameForm_proc (struct cFrameForm *ptr_frame_form, struct Message *ptr_message)
void | cFrameForm_Disconnect (struct cFrameForm *ptr_frame_form)
bool | cFrameForm_Select (struct cFrameForm *ptr_frame_form)
void | cFrameForm_update (struct cFrameForm *ptr_frame_form)
struct cClip* | cFrameForm_GetParent (struct cFrameForm *ptr_frame_form)
void | cFrameForm_Hide (struct cFrameForm *ptr_frame_form)
void | cFrameForm_Show (struct cFrameForm *ptr_frame_form)
void | cFrameForm_Disable (struct cFrameForm *ptr_frame_form)
void | cFrameForm_Enable (struct cFrameForm *ptr_frame_form)
void | cFrameForm_AddObj (struct cFrameForm *ptr_frame_form, struct cObject *ptr_object, int x, int y)
void | cFrameForm_InsObj (struct cFrameForm *ptr_frame_form, struct cObject *ptr_object, int x, int y, int index)
void | cFrameForm_RemObj (struct cClip *ptr_frame_form, struct cObject *ptr_object)
bool | cFrameForm_SelectFirst (struct cFrameForm *ptr_frame_form)
bool | cFrameForm_SelectPrev (struct cFrameForm *ptr_frame_form, bool round)
bool | cFrameForm_SelectNext (struct cFrameForm *ptr_frame_form, bool round)
void | cFrameForm_Scroll (struct cFrameForm *ptr_frame_form, struct rect_t *rectangle)
void | cFrameForm_Scroll_Ex (struct cFrameForm *ptr_frame_form, int x, int y)
void | cFrameForm_SendScroll (struct cFrameForm *ptr_frame_form)
int | cFrameForm_GetShifty (struct cFrameForm *ptr_frame_form)
int | cFrameForm_GetShiftx (struct cFrameForm *ptr_frame_form)
int | cFrameForm_GetCount (struct cFrameForm *ptr_frame_form)
struct cObject* | cFrameForm_get_by_index (struct cFrameForm *ptr_frame_form, int index)
int | cFrameForm_FindObj (struct cFrameForm *ptr_frame_form, struct cObject *ptr_object)
struct cObject* | cFrameForm_GetSelectedObject (struct cFrameForm *ptr_frame_form)

Detailed Description

This is the structure for creating a full-screen window with a frame.

After creating the form, you can show it (see cFrameForm_ShowModal) and then when a message comes in, you can process it by calling the cDialog_proc function.

You must call the cFrameForm_ctor function before use and cFrameForm_dtor function after use.

See also:
Forms & Containers , cDialog_proc

Member Function Documentation

void cFrameForm_AddObj ( | struct cFrameForm * ptr_frame_form,
 | struct cObject * ptr_object,
 | int x,
 | int y )

Adds an object to the cFrameForm in position (x, y).

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object.
ptr_object | A pointer to the initialized cObject structure
x | x-coordinate of the new object
y | y-coordinate of the new object
Returns:
None

void cFrameForm_Disable ( struct cFrameForm * ptr_frame_form )

Disables a cFrameForm object so that it cannot be selected.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None
See also:
cFrameForm_Enable.

void cFrameForm_Disconnect ( struct cFrameForm * ptr_frame_form )

Disconnects a cFrameForm from its parent object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None

void cFrameForm_Enable ( struct cFrameForm * ptr_frame_form )

Enables a cFrameForm object so that it may be selected.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None
See also:
cFrameForm_Disable.

int cFrameForm_FindObj ( | struct cFrameForm * ptr_frame_form,
 | struct cObject * ptr_object )

Returns the child object's index in the cFrameForm (or -1 ).

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
ptr_object | A pointer to the initialized cObject object
Returns:
The child object's index in the cFrameForm (or -1 )

int cFrameForm_GetCount ( struct cFrameForm * ptr_frame_form )

Returns the count of child objects.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
Child objects count

struct cClip * cFrameForm_GetParent ( struct cFrameForm * ptr_frame_form )

Returns a pointer to the parent object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
A pointer to the parent object

struct cObject * cFrameForm_GetSelectedObject ( struct cFrameForm * ptr_frame_form )

Returns the currently selected object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
The currently selected object

int cFrameForm_GetShiftx ( struct cFrameForm * ptr_frame_form )

Returns the 'x' coordinate shift (as a result of scrolling).

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
'x' coordinate shift (as a result of scrolling)

int cFrameForm_GetShifty ( struct cFrameForm * ptr_frame_form )

Returns the 'y' coordinate shift (as a result of scrolling).

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
'y' coordinate shift (as a result of scrolling)

void cFrameForm_Hide ( struct cFrameForm * ptr_frame_form )

Hides a cFrameForm object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None
   #include <cywin.h>
    ...
    // Application's main form
    struct cFrameForm* ptr_main_form;
    ...
    // Selects the effect
    cMainForm_ShowModal( ptr_main_form );
    ...
    cFrameForm_Hide( ptr_main_form );
    ...
See also:
cFrameForm_Show.

void cFrameForm_InsObj ( | struct cFrameForm * ptr_frame_form,
 | struct cObject * ptr_object,
 | int x,
 | int y,
 | int index )

Adds an object to the cFrameForm in a position ( x, y ) with a z-position index (maximal index is on the top).

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
ptr_object | A pointer to initialized cObject structure
x | The x-coordinate of the new object
y | The y-coordinate of the new object
index | z-position of the new object
Returns:
None

void cFrameForm_RemObj ( | struct cClip * ptr_frame_form,
 | struct cObject * ptr_object )

Removes an object from a cFrameForm.

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object.
ptr_object | A pointer to the initialized cObject structure
Returns:
None

void cFrameForm_Scroll ( | struct cFrameForm * ptr_frame_form,
 | struct rect_t * rectangle )

Scrolls a cFrameForm to make a rectangle visible.
Provides minimal scrolling.

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
rectangle | A pointer to the initialized rect_t structure
Returns:
None
See also:
cFrameForm_Scroll_Ex.

void cFrameForm_Scroll_Ex ( | struct cFrameForm * ptr_frame_form,
 | int x,
 | int y )

Scrolls a cFrameForm by (x, y), but cannot exceed the child's boundaries.

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
x | "x" coordinate shift
y | "y" coordinate shift
Returns:
None
See also:
cFrameForm_Scroll.

bool cFrameForm_Select ( struct cFrameForm * ptr_frame_form )

Selects a cFrameForm object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
TRUE if the object was selected.

bool cFrameForm_SelectFirst ( struct cFrameForm * ptr_frame_form )

Selects the first object in the cFrameForm.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
FALSE if the function failed

bool cFrameForm_SelectNext ( | struct cFrameForm * ptr_frame_form,
 | bool round )

Selects the next object in the cFrameForm.

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
round | is TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed

bool cFrameForm_SelectPrev ( | struct cFrameForm * ptr_frame_form,
 | bool round )

Selects the previous object in the cFrameForm.

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
round | TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed

void cFrameForm_SendScroll ( struct cFrameForm * ptr_frame_form )

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None

void cFrameForm_Show ( struct cFrameForm * ptr_frame_form )

Shows a cFrameForm object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None
   #include <cywin.h>
   ...
   int cMainForm_ShowModal( struct cFrameForm* ptr_form )
   {
     cFrameForm_Show( ptr_form );
     ...
     ptr_form->ModalResult = mrNone;
     ...
     while( ptr_form->ModalResult == mrNone  &&
       ptr_menu_form->ModalResult != mrQuit )
     {
      struct Message *ptr_message =
        cWinApp_get_message( ptr_form->CurrApplication,
          0, 1, MSG_USER );
      ...
      cMainForm_proc( ptr_form, ptr_message );
      ...
      Message_delete( ptr_message );
     }
     return ptr_form->ModalResult;
   }
   ...
See also:
cFrameForm_Hide.

int cFrameForm_ShowModal ( struct cFrameForm * ptr_frame_form )

Shows a cFrameForm in modal mode.
This function shows the cFrameForm and enters it into the message loop. The loop continues until any one ModalResult variable is set to a non-zero value, or until a MSG_QUIT or MSG_SHUTUP messages is received. If these messages are received, the function reposts them to the application and leaves the message loop. This is how all forms will close when the application ends.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
tMResults value. mrNone(Zero) if MSG_QUIT or MSG_SHUTUP messages initiates leaving the loop. There are some predefined results
   #include <cywin.h>
     ...
     struct cFrameForm frame_form;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cFrameForm_ctor( &frame_form, "Caption", main_module.m_process );
     ...
     // Adding some objects to the custom form.
     ...
     cFrameForm_ShowModal( &frame_form );
     ...
     cFrameForm_dtor( &frame_form, LEAVE_MEMORY );
See also:
tMResults , MSG_QUIT , MSG_SHUTUP

struct cFrameForm * cFrameForm_ctor ( | struct cFrameForm * ptr_frame_form,
 | char * text,
 | struct cWinApp * ptr_win_app )

Constructor.
Creates the full-screen window form.

Parameters:
ptr_frame_form | A pointer to a cFrameForm object
text | The form's caption
ptr_win_app | A pointer to the structure of the current cywin application
Returns:
A pointer to the initialized cFrameForm object
   #include <cywin.h>
     ...
     struct cFrameForm frame_form;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cFrameForm_ctor( &frame_form, "Caption", main_module.m_process );
     ...
     // Adding some objects to the custom form.
     ...
     cFrameForm_ShowModal( &frame_form );
     ...
     cFrameForm_dtor( &frame_form, LEAVE_MEMORY );

void cFrameForm_dtor ( struct cFrameForm * ptr_frame_form )

Deletes the cFrameForm object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None
   #include <cywin.h>
     ...
     struct cFrameForm frame_form;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cFrameForm_ctor( &frame_form, "Caption", main_module.m_process );
     ...
     // Adding some objects to the custom form.
     ...
     cFrameForm_ShowModal( &frame_form );
     ...
     cFrameForm_dtor( &frame_form, LEAVE_MEMORY );

struct cObject * cFrameForm_get_by_index ( | struct cFrameForm * ptr_frame_form,
 | int index )

Returns an object's index (or NULL).

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
index | Object's index
Returns:
Object's index (or NULL)

bool cFrameForm_proc ( | struct cFrameForm * ptr_frame_form,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_frame_form | A pointer to the initialized cFrameForm object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed
   #include <cywin.h>
    ...
    bool cMainForm_proc( struct cFrameForm* ptr_form, struct Message* ptr_message )
    {
      switch( ptr_message->msgid )
      {
        case MSG_SHUTUP: // Processes the system exit signal
        case MSG_QUIT:
        ...
        ptr_form->ModalResult = mrQuit;
        ...
        break;
        ...
        case MSG_KEYDOWN: // Processes the keyboard
        ...
        switch( Message_get_key_param( ptr_message )->scancode )
        {
          case KEY_ESC:
          ...
          ptr_form->ModalResult = mrQuit;
          ...
          return TRUE;
          ...
          case KEY_ENTER:
          ...
          // ModalResult containing the selected menu item
          ptr_form->ModalResult = mrOk;
          ...
          return TRUE;
        }
      }
      return cFrameForm_proc( ptr_form, ptr_message );
    }
    ...

void cFrameForm_update ( struct cFrameForm * ptr_frame_form )

Updates a cFrameForm object.

Parameters:
ptr_frame_form A pointer to the initialized cFrameForm object
Returns:
None
   #include <cywin.h>
    ...
    int cMainForm_ShowModal( struct cFrameForm* ptr_form )
    {
      ptr_form->HelpContext = 0;
      ...
      cFrameForm_Show( ptr_form );
      ...
      ptr_form->ModalResult = mrNone;
      ...
      while( ptr_form->ModalResult == mrNone )
      {
        struct Message* ptr_message =
          cWinApp_get_message( ptr_form->CurrApplication, 0, 1, MSG_USER );
        ...
        cMainForm_proc( ptr_form, ptr_message );
        ...
        cFrameForm_update( ptr_form );
        ...
        Message_delete( ptr_message );
      }
      return ptr_form->ModalResult;
    }
    ...


Controls

Enumerations
enum tBevelSidesTypes {
Top = 1,
Bottom = 2,
Left = 4,
Right = 8,
All = 15
}
enum tEditStyles {
es_normal = 0,
es_readonly = 1,
es_password = 2,
es_centered = 4
}
enum tEditCursorCommand {
mc_lineup = 0,
mc_linedown = 1,
mc_pageup = 2,
mc_pagedown = 3,
mc_home = 4,
mc_end = 5
}

Compounds
struct | cBevel | CBevel object is an outlined empty rectangle
struct | cBitmap | Use this structure to place a simple picture on the screen
struct | cBox | CBox is simply a filled rectangle
struct | cButton | A basic button
struct | cEdit | This structure puts a standard edit control on the Cybiko screen
struct | cItem | This structure implements methods for working with simple units of the list, such as a text string
struct | cList | This structure implements methods for working with a list and a menu
struct | cProgressBar | Adds a progress bar to your application
struct | cSItem | A cSItem object might have an icon on the left and/or additional text on the right
struct | cText | Static, transparent text line
struct | cXByte | A framed string with an icon on the left
struct | cXItem | The same type of string as in the cItem structure
struct | cXStr | A cXStr object might have an icon on the left and/or additional text on the right

Detailed Description

This section groups standard controls found on many systems, such as cList (a list of selectable strings), cButton (a button with associated text and return value), cEdit (textual entry field), etc. These controls could be attached to the above described forms. Please note that cDialog is nothing else but a cCustomForm with several controls attached to it, according to the flags (its 'style') you pass to its constructor.

Enumeration Type Documentation

enum tBevelSidesTypes

The visible styles for creating a bevel's sides.

Enumeration values:
Top | the top side of a bevel.
Bottom | the bottom side of a bevel.
Left | the left side of a bevel.
Right | the right side of a bevel.
All | show all of the bevel's sides.

enum tEditCursorCommand

Commands for cursor positioning.

Enumeration values:
mc_lineup | move the cursor one line up.
mc_linedown | move the cursor one line down.
mc_pageup | move the cursor one page up.
mc_pagedown | move the cursor one page down.
mc_home | move the cursor to the beginning of the string.
mc_end | move the cursor to the end of the string.

enum tEditStyles

Edit box styles.

Enumeration values:
es_normal | show the text as entered.
es_readonly | show text as read-only; no editing allowed.
es_password | show all characters as '*' onscreen regardless of what characters are entered (however, in this mode the actual text is stored with correct characters, which may be accessed via password).
es_centered | center each line within the given rectangle.


cBevel Struct Reference

Inheritance diagram for cBevel

Collaboration diagram for cBevel:

Public Methods
struct cBevel* | cBevel_ctor (struct cBevel *, int, int, color_t, char)
void | cBevel_dtor (struct cBevel *, int)
bool | cBevel_proc (struct cBevel *ptr_cbevel, struct Message *ptr_message)
void | cBevel_Disconnect (struct cBevel *ptr_cbevel)
bool | cBevel_Select (struct cBevel *ptr_cbevel)
void | cBevel_update (struct cBevel *ptr_cbevel)
struct cClip* | cBevel_GetParent (struct cBevel *ptr_cbevel)
void | cBevel_Hide (struct cBevel *ptr_cbevel)
void | cBevel_Show (struct cBevel *ptr_cbevel)
void | cBevel_Disable (struct cBevel *ptr_cbevel)
void | cBevel_Enable (struct cBevel *ptr_cbevel)

Detailed Description

The cBevel object is an outlined empty rectangle. The cBevel structure lets you put beveled lines, boxes, or frames on the Cybiko screen. Any side of the rectangle can be visible or invisible.

The default is for all sides to be visible. The visibility values for all sides are defined in the tBevelSidesTypes enumeration and described in the 'Enums' section.

See also:
Controls

Member Function Documentation

void cBevel_Disable ( struct cBevel * ptr_cbevel )

Disables the cBevel object so that it cannot be selected.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBevel_Enable.

void cBevel_Disconnect ( struct cBevel * ptr_cbevel )

Disconnects cBevel from its parent object.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
None
    #include <cywin.h>
    ...
    struct cBitmap cbmp;
    struct Bitmap bmp;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    // Creates a bitmap from the file "root.ico".
    Bitmap_ctor_Ex1( &bmp, "root.ico" );
    cBitmap_ctor( &cbmp, &bmp );
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Removes the object from the Cybiko screen.
    // It's the same as using the cObject_Disconnect( &cbmp ) function.
    cBitmap_Disconnect( &cbmp );
    ...
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Afterwards this function disconnects the cBitmap object automatically.
    cBitmap_dtor( &cbmp, LEAVE_MEMORY );
    Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cBevel_Enable ( struct cBevel * ptr_cbevel )

Enables the cBevel object so that it may be selected.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBevel_Disable.

struct cClip * cBevel_GetParent ( struct cBevel * ptr_cbevel )

Returns a pointer to the parent object's cClip.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
A pointer to the parent object's cClip
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_GetParent( &button ) function.
    // Checks for the right parent relation.
    parent = cObject_GetParent( &button );
    if ( parent == main_module.m_process )
    {
      ...
    }
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

void cBevel_Hide ( struct cBevel * ptr_cbevel )

Hides the cBevel object.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBevel_Show.

bool cBevel_Select ( struct cBevel * ptr_cbevel )

Selects cBevel object.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
TRUE if the object was selected
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Select( &button ) function.
    // Selects the button.
    cObject_Select( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

void cBevel_Show ( struct cBevel * ptr_cbevel )

Shows the cBevel object.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBevel_Hide.

struct cBevel * cBevel_ctor ( | struct cBevel * ptr_cbevel,
 | int w,
 | int h,
 | color_t color,
 | char sides )

Constructor.
Creates an empty cBevel object.

Parameters:
ptr_cbevel | A pointer to the initialized cBevel object
w | The box width
h | The box height
color | The object's color
sides | The visibility state of the box sides. See 'tBevelSidesTypes' enumeration in the 'Enums' section
Returns:
A pointer to the initialized cBevel object
       #include <cywin.h>
       ...
       struct cBevel cbevel;
       struct module_t main_module;
       ...
       init_module( &main_module );
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cBevel_ctor( &cbox, 100, 100, CLR_LTGRAY, Left | Right );
       // Puts the cBevel object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbevel, 10, 40 );
       ...
       cBox_dtor( &cbevel, LEAVE_MEMORY );
See also:
cBevel_dtor.

void cBevel_dtor ( | struct cBevel * ptr_cbevel,
 | int memory_flag )

Destructor.
Deletes an object.

Parameters:
ptr_cbevel | A pointer to the initialized cBevel object.
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in stack
Returns:
None
       #include <cywin.h>
       ...
       struct cBevel cbevel;
       struct module_t main_module;
       ...
       init_module( &main_module );
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cBevel_ctor( &cbox, 100, 100, CLR_LTGRAY, Left | Right );
       // Puts the cBevel object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbevel, 10, 40 );
       ...
       cBox_dtor( &cbevel, LEAVE_MEMORY );
See also:
cBevel_ctor, FREE_MEMORY, LEAVE_MEMORY.

bool cBevel_proc ( | struct cBevel * ptr_cbevel,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cbevel | A pointer to the initialized cBevel structure
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed
    #include <cywin.h>
    ...
    struct cBitmap cbmp;
    struct Bitmap bmp;
    struct module_t main_module;
    struct Message* ptr_message;
    ...
    init_module( &main_module );
    ...
    // Creates a bitmap from the file "root.ico".
    Bitmap_ctor_Ex1( &bmp, "root.ico" );
    cBitmap_ctor( &cbmp, &bmp );
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
    // It's the same as using the cObject_proc( &cbmp, ptr_message ) function.
    // Processes messages that manage the cBitmap control.
    cBitmap_proc( &cbmp, ptr_message );
    ...
    // Afterwards this function disconnects the cBitmap object automatically.
    cBitmap_dtor( &cbmp, LEAVE_MEMORY );
    Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cBevel_update ( struct cBevel * ptr_cbevel )

Updates a cBevel object.

Parameters:
ptr_cbevel A pointer to the initialized cBevel structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    cWinApp_clear_screen();
    // It's the same as using the cButton_update( &button ) function.
    // Redraws the button.
    cObject_update( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );


cBitmap Struct Reference

Inheritance diagram for cBitmap

Collaboration diagram for cBitmap:

Public Methods
struct cBitmap* | cBitmap_ctor (struct cBitmap *, struct Bitmap *)
struct cBitmap* | cBitmap_ctor_Ex (struct cBitmap *, struct Bitmap *, color_t)
void | cBitmap_dtor (struct cBitmap *, int)
void | cBitmap_SetFlips (struct cBitmap *, short)
bool | cBitmap_proc (struct cBitmap *ptr_cbitmap, struct Message *ptr_message)
void | cBitmap_Disconnect (struct cBitmap *ptr_cbitmap)
bool | cBitmap_Select (struct cBitmap *ptr_cbitmap)
void | cBitmap_update (struct cBitmap *ptr_cbitmap)
struct cClip* | cBitmap_GetParent (struct cBitmap *ptr_cbitmap)
void | cBitmap_Hide (struct cBitmap *ptr_cbitmap)
void | cBitmap_Show (struct cBitmap *ptr_cbitmap)
void | cBitmap_Disable (struct cBitmap *ptr_cbitmap)
void | cBitmap_Enable (struct cBitmap *ptr_cbitmap)

Detailed Description

Use this structure to put a simple picture on the screen.

See also:
Controls

Member Function Documentation

void cBitmap_Disable ( struct cBitmap * ptr_cbitmap )

Disables a cBitmap object so that it cannot be selected.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBitmap_Enable.

void cBitmap_Disconnect ( struct cBitmap * ptr_cbitmap )

Disconnects a cBitmap from its parent object.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
None
    #include <cywin.h>
    ...
    struct cBitmap cbmp;
    struct Bitmap bmp;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    // Creates a bitmap from the file "root.ico".
    Bitmap_ctor_Ex1( &bmp, "root.ico" );
    cBitmap_ctor( &cbmp, &bmp );
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Removes the object from the Cybiko screen.
    //It's the same as using the cObject_Disconnect( &cbmp ) function.
    cBitmap_Disconnect( &cbmp );
    ...
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Afterwards this function disconnects the cBitmap object automatically.
    cBitmap_dtor( &cbmp, LEAVE_MEMORY );
    Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cBitmap_Enable ( struct cBitmap * ptr_cbitmap )

Enables a cBitmap object so that it may be selected.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBitmap_Disable.

struct cClip * cBitmap_GetParent ( struct cBitmap * ptr_cbitmap )

Returns a pointer to the parent object's cClip.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
A pointer to the parent object's cClip
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_GetParent( &button ) function.
    // Checks for the right parent relation.
    parent = cObject_GetParent( &button );
    if ( parent == main_module.m_process )
    {
      ...
    }
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

void cBitmap_Hide ( struct cBitmap * ptr_cbitmap )

Hides a cBitmap object.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBitmap_Show.

bool cBitmap_Select ( struct cBitmap * ptr_cbitmap )

Selects a cBitmap object.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
TRUE if the object was selected
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Select( &button ) function.
    // Selects the button.
    cObject_Select( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

void cBitmap_SetFlips ( | struct cBitmap * ptr_cbitmap,
 | short flip )

Changes the 'flip' state.

Parameters:
ptr_cbitmap | A pointer to the initialized cBitmap object
flip | A flip state flag. It may be any combination of the following: BM_NORMAL, BM_INVERSE, BM_FLIP_X, BM_FLIP_Y
Returns:
None
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cBitmap_ctor_Ex( &cbmp, &bmp, CLR_LTGRAY );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
       ...
       cBitmap_SetFlips( &cbmp, BM_FLIP_X );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
See also:
BM_NORMAL , BM_INVERSE , BM_FLIP_X , BM_FLIP_Y

void cBitmap_Show ( struct cBitmap * ptr_cbitmap )

Shows a cBitmap object.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBitmap_Hide.

struct cBitmap * cBitmap_ctor ( | struct cBitmap * ptr_cbitmap,
 | struct Bitmap * ptr_pic )

Constructor for a non-transparent picture.

Parameters:
ptr_cbitmap | A pointer to the cBitmap object
ptr_pic | A pointer to a template cBitmap object
Returns:
A pointer to the initialized cBitmap object
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       cBitmap_ctor( &cbmp, &bmp );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
See also:
cBitmap_ctor_Ex.

struct cBitmap * cBitmap_ctor_Ex ( | struct cBitmap * ptr_cbitmap,
 | struct Bitmap * ptr_pic,
 | color_t color )

Extended version of the cBitmap_ctor function.
Constructs a transparent picture.

Parameters:
ptr_cbitmap | A pointer to the cBitmap struct
ptr_pic | A pointer to the template cBitmap object
color | A transparent color
Returns:
A pointer to the initialized cBitmap object
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       // The color value may be following: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cBitmap_ctor_Ex( &cbmp, &bmp, CLR_LTGRAY );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
See also:
cBitmap_ctor.

void cBitmap_dtor ( | struct cBitmap * ptr_cbitmap,
 | int memory_flag )

Destructor.
Deletes an object.

Parameters:
ptr_cbitmap | A pointer to the initialized cBitmap object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if the object was static or allocated in stack
Returns:
None
       #include <cywin.h>
       ...
       struct cBitmap cbmp;
       struct Bitmap bmp;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       // The color value should have as follows: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cBitmap_ctor_Ex( &cbmp, &bmp, CLR_LTGRAY );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
       ...
       cBitmap_dtor( &cbmp, LEAVE_MEMORY );
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cBitmap_proc ( | struct cBitmap * ptr_cbitmap,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cbitmap | A pointer to the initialized cBitmap object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed
    #include <cywin.h>
    ...
    struct cBitmap cbmp;
    struct Bitmap bmp;
    struct module_t main_module;
    struct Message* ptr_message;
    ...
    init_module( &main_module );
    ...
    // Creates a bitmap from the file "root.ico".
    Bitmap_ctor_Ex1( &bmp, "root.ico" );
    cBitmap_ctor( &cbmp, &bmp );
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
    // It's the same as using the cObject_proc( &cbmp, ptr_message ) function.
    // Processes mesages that manages the cBitmap control.
    cBitmap_proc( &cbmp, ptr_message );
    ...
    // Afterwards this function disconnects the cBitmap object automatically.
    cBitmap_dtor( &cbmp, LEAVE_MEMORY );
    Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cBitmap_update ( struct cBitmap * ptr_cbitmap )

Updates a cBitmap object.

Parameters:
ptr_cbitmap A pointer to the initialized cBitmap object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    cWinApp_clear_screen();
    // It's the same as using the cButton_update( &button ) function.
    // Redraws the button.
    cObject_update( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );


cBox Struct Reference

Inheritance diagram for cBox

Collaboration diagram for cBox:

Public Methods
struct cBox* | cBox_ctor (struct cBox *ptr_cbox, int w, int h, color_t color, bool transparent)
void | cBox_dtor (struct cBox *ptr_cbox, int memory_flag)
bool | cBox_proc (struct cBox *ptr_cbox, struct Message *ptr_message)
void | cBox_Disconnect (struct cBox *ptr_cbox)
bool | cBox_Select (struct cBox *ptr_cbox)
void | cBox_update (struct cBox *ptr_cbox)
struct cClip* | cBox_GetParent (struct cBox *ptr_cbox)
void | cBox_Hide (struct cBox *ptr_cbox)
void | cBox_Show (struct cBox *ptr_cbox)
void | cBox_Disable (struct cBox *ptr_cbox)
void | cBox_Enable (struct cBox *ptr_cbox)

Detailed Description

A filled rectangle. To put a cBox on the Cybiko screen, use the cWinApp_AddObj() function.

See also:
Controls, cWinApp_AddObj

Member Function Documentation

void cBox_Disable ( struct cBox * ptr_cbox )

Disables a cBox object so that it cannot be selected.

Parameters:
ptr_cbox A pointer to the initialized cBox structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBox_Enable.

void cBox_Disconnect ( struct cBox * ptr_cbox )

Disconnects a cBox object from its parent object.

Parameters:
ptr_cbox A pointer to the initialized cBox object
Returns:
None
      #include <cywin.h>
      ...
      struct cBox cbox;
      struct module_t main_module;
      ...
      init_module( &main_module );
      ...
      cBox_ctor( &cbox, 100, 100, CLR_LTGRAY, TRUE );
      // Puts the cBox object on the Cybiko screen.
      cWinApp_AddObj( main_module.m_process, &cbox, 10, 40 );
      ...
      // Removes the cBox object from the Cybiko screen.
      cBox_Disconnect( &cbmp );
      ...
      // Puts the cBox object on the Cybiko screen again.
      cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
      ...
      cBox_dtor( &cbox, LEAVE_MEMORY );
      ...

void cBox_Enable ( struct cBox * ptr_cbox )

Enables a cBox object - so that it may be selected.

Parameters:
ptr_cbox A pointer to the initialized cBox structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBox_Disable.

struct cClip * cBox_GetParent ( struct cBox * ptr_cbox )

Returns a pointer to the parent object's cClip.

Parameters:
ptr_cbox A pointer to the initialized cBox structure
Returns:
A pointer to the parent object
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_GetParent( &button ) function.
    // Checks for the right parent relation.
    parent = cObject_GetParent( &button );
    if ( parent == main_module.m_process )
    {
      ...
    }
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

void cBox_Hide ( struct cBox * ptr_cbox )

Hides a cBox object.

Parameters:
ptr_cbox A pointer to the initialized cBox structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBox_Show.

bool cBox_Select ( struct cBox * ptr_cbox )

Selects a cBox object.

Parameters:
ptr_cbox A pointer to the initialized cBox object
Returns:
TRUE if object was selected, otherwise FALSE.
       #include <cywin.h>
       ...
       struct cBox cbox;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // It's the same as using the cButton_Select( &button ) function.
       // Selects the button.
       cObject_Select( &button );
       ...
       cButton_dtor( &button, LEAVE_MEMORY );

void cBox_Show ( struct cBox * ptr_cbox )

Shows a cBox object.

Parameters:
ptr_cbox A pointer to the initialized cBox structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cBox_Hide.

struct cBox * cBox_ctor ( | struct cBox * ptr_cbox,
 | int w,
 | int h,
 | color_t color,
 | bool transparent )

Constructor.
Creates an empty cBox object.

Parameters:
ptr_cbox | A pointer to the initialized cBox object
w | The box width
h | The box height
color | The box color
transparent | Transparent mode. If TRUE, the cBox is transparent
Returns:
A pointer to the initialized cBox object
       #include <cywin.h>
       ...
       struct cBox cbox;
       struct module_t main_module;
       ...
       init_module( &main_module );
       cBox_ctor( &cbox, 100, 100, CLR_LTGRAY, TRUE );
       // Puts the cBox object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbox, 10, 40 );
       ...
       cBox_dtor( &cbox, LEAVE_MEMORY );
See also:
cBox_dtor.

void cBox_dtor ( | struct cBox * ptr_cbox,
 | int memory_flag )

Destructor.
Deletes the cBox.

Parameters:
ptr_cbox | A pointer the initialized cBox object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if object was static or allocated in stack.
Returns:
None.
       #include <cywin.h>
       ...
       struct cBox cbox;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cBox_ctor( &cbox, 100, 100, CLR_LTGRAY, TRUE );
       // Puts the cBox object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbox, 10, 40 );
       ...
       cBox_dtor( &cbox, LEAVE_MEMORY );
See also:
cBox_ctor, FREE_MEMORY, LEAVE_MEMORY.

bool cBox_proc ( | struct cBox * ptr_cbox,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cbox | A pointer to the initialized cBox object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed, otherwise FALSE
       #include <cywin.h>
       ...
       struct cBox cbox;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       cBox_ctor( &cbox, 100, 100, CLR_LTGRAY, TRUE );
       // Puts the cBox object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cbox, 10, 40 );
       ...
       ptr_message = cWinApp_get_message( main_module.m_process,
                                          0,
                                          1,
                                          MSG_USER );
       //  Processes messages using the cBox message handler.
       cBox_proc( &cbox, ptr_message );
       ...
       cBox_dtor( &cbox, LEAVE_MEMORY );
       ...

void cBox_update ( struct cBox * ptr_cbox )

Updates a cBox object.

Parameters:
ptr_cbox A pointer to the initialized cBox structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    cWinApp_clear_screen();
    // It's the same as using the cButton_update( &button ) function.
    // Redraws the button.
    cObject_update( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );


cButton Struct Reference

Inheritance diagram for cButton

Collaboration diagram for cButton:

Public Methods
struct cButton* | cButton_ctor (struct cButton *ptr_cbutton, char *text, int modal_result)
void | cButton_dtor (struct cButton *ptr_cbutton, int memory_flag)
int | cButton_GetModalResult (struct cButton *ptr_cbutton)
bool | cButton_proc (struct cButton *ptr_cbutton, struct Message *ptr_message)
void | cButton_Enable (struct cButton *ptr_cbutton)
void | cButton_Disable (struct cButton *ptr_cbutton)
void | cButton_Show (struct cButton *ptr_cbutton)
void | cButton_Hide (struct cButton *ptr_cbutton)
void | cButton_Disconnect (struct cButton *ptr_cbutton)
bool | cButton_Select (struct cButton *ptr_cbutton)
void | cButton_update (struct cButton *ptr_cbutton)
struct cClip* | cButton_GetParent (struct cButton *ptr_cbutton)

Detailed Description

A basic button. You can add a button to any user form, as well as to the Cybiko screen.

Every button must have its own modal result, which can be defined in the third parameter of the cButton_ctor function. Variants of modal results are contained in the tmResults enumeration. Every button can have a message-processing function.

You must call the cButton_ctor function before use and the cButton_dtor function after use.

See also:
Controls

Member Function Documentation

void cButton_Disable ( struct cButton * ptr_cbutton )

Disables the cButton object so that it cannot be selected..

Parameters:
ptr_cbutton A pointer to the initialized cButton object
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     struct cClip* parent;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // It's the same as using the cButton_Disable( &button ) function.
     // Now the user can't use this object.
     cButton_Disable( &button )
     ...
     // It's the same as using the cButton_Enable( &button ) function.
     // Now the user can use this object again.
     cButton_Enable( &button )
     ...
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
cButton_Enable.

void cButton_Disconnect ( struct cButton * ptr_cbutton )

Disconnects the cButton object from its parent object.

Parameters:
ptr_cbutton A pointer to the initialized cButton object
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // Removes the object from the Cybiko screen.
     cButton_Disconnect( &button);
     ...
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     // Afterwards this function disconnects the cText object automatically
     cButton_dtor( &button, LEAVE_MEMORY );

void cButton_Enable ( struct cButton * ptr_cbutton )

Enables the cButton object so that it may be selected.

Parameters:
ptr_cbutton A pointer to the initialized cButton object
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     struct cClip* parent;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // It's the same as using the cButton_Disable( &button ) function.
     // Now the user can't use this object.
     cButton_Disable( &button )
     ...
     // It's the same as using the cButton_Enable( &button ) function.
     // Now the user can use this object again.
     cButton_Enable( &button )
     ...
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
cButton_Disable.

int cButton_GetModalResult ( struct cButton * ptr_cbutton )

Returns the button modal result, which was set in the cButton constructor.

Parameters:
ptr_cbutton A pointer to the initialized cButton object
Returns:
The button modal result
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     if ( cButton_GetModalResult( &button ) == mrOk )
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

struct cClip * cButton_GetParent ( struct cButton * ptr_cbutton )

Returns a pointer to the parent object.

Parameters:
ptr_cbutton A pointer to the initialized cButton object
Returns:
A pointer to the parent object
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     struct cClip* parent;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // It's the same as using the cButton_GetParent( &button ) function.
     // Checks for the right parent relation.
     parent = cObject_GetParent( &button );
     if ( parent == main_module.m_process )
     {
     }
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

void cButton_Hide ( struct cButton * ptr_cbutton )

Hides a cButton object.

Parameters:
ptr_cbutton A pointer to the initialized cButton object.
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // It's the same as using the cButton_Hide( &button ) function.
     cObject_Hide( &button );
     ...
     // It's the same as using the cButton_Show( &button ) function.
     cObject_Show( &button );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
cButton_Show.

bool cButton_Select ( struct cButton * ptr_cbutton )

Selects a cButton object.

Parameters:
ptr_cbutton A pointer to the initialized cButton object
Returns:
TRUE if the object was selected
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // It's the same as using the cButton_Select( &button ) function.
     // Selects the button.
     cButton_Select( &button );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

void cButton_Show ( struct cButton * ptr_cbutton )

Shows cButton object.

Parameters:
ptr_cbutton A pointer to the initialized cButton object.
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     // It's the same as using the cButton_Hide( &button ) function.
     cObject_Hide( &button );
     ...
     // It's the same as using the cButton_Show( &button ) function.
     cObject_Show( &button );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
cButton_Hide.

struct cButton * cButton_ctor ( | struct cButton * ptr_cbutton,
 | char * text,
 | int modal_result )

Initializes a cButton object.

Parameters:
ptr_cbutton | A pointer to a cButton object
text | The button's text
modal_result | Will be set in cForm when the button is pressed
Returns:
A pointer to the initialized cButton object
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

void cButton_dtor ( | struct cButton * ptr_cbutton,
 | int memory_flag )

Deletes a cButton object.

Parameters:
ptr_cbutton | A pointer to the initialized cButton object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if the object was static or allocated in stack
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     cButton_dtor( &button, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cButton_proc ( | struct cButton * ptr_cbutton,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cbutton | A pointer to the initialized cButton object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       //  If user presses 'Enter' button will be pushed.
       cButton_proc( &button, ptr_message);
     }
     ...
     cButton_dtor( &button, LEAVE_MEMORY );

void cButton_update ( struct cButton * ptr_cbutton )

Updates a cButton object.

Parameters:
ptr_cbutton A pointer to the initialized cButton object
Returns:
None
   #include <cywin.h>
     ...
     struct cButton button;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cButton_ctor( &button, "Button text", mrOk );
     // Puts the 'button' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
     ...
     cWinApp_clear_screen();
     // It's the same as using the cButton_update( &button ) function.
     // Redraws the button.
     cButton_update( &button )
     ...
     cButton_dtor( &button, LEAVE_MEMORY );


cEdit Struct Reference

Inheritance diagram for cEdit

Collaboration diagram for cEdit:

Public Methods
struct cEdit* | cEdit_ctor (struct cEdit *ptr_cedit, struct Font *ptr_cfont, int buffer_size, int style, color_t color, int width)
void | cEdit_dtor (struct cEdit *ptr_cedit, int memory_flag)
void | cEdit_HighliteText (struct cEdit *, bool flag)
bool | cEdit_SetReadOnly (struct cEdit *ptr_cedit, bool state)
int | cEdit_SetPageLineCount (struct cEdit *ptr_cedit, int lines)
bool | cEdit_IsHighlited (struct cEdit *ptr_cedit)
int | cEdit_SetCursorPos (struct cEdit *ptr_cedit, int position)
int | cEdit_MoveCursor (struct cEdit *ptr_cedit, int reg)
int | cEdit_GetCursorPos (struct cEdit *ptr_cedit)
int | cEdit_SetText (struct cEdit *ptr_cedit, char *text)
int | cEdit_AppendText (struct cEdit *ptr_cedit, char *text)
int | cEdit_SetText_Ex (struct cEdit *ptr_cedit, struct Input *ptr_input)
int | cEdit_GetText_Ex (struct cEdit *ptr_cedit, struct Output *ptr_output)
bool | cEdit_IsModified (struct cEdit *ptr_cedit)
int | cEdit_GetTextLength (struct cEdit *ptr_cedit)
char* | cEdit_GetBufferPtr (struct cEdit *)
int | cEdit_GetText (struct cEdit *, char *)
bool | cEdit_proc (struct cEdit *ptr_cedit, struct Message *ptr_message)
void | cEdit_Disconnect (struct cEdit *ptr_cedit)
bool | cEdit_Select (struct cEdit *ptr_cedit)
void | cEdit_update (struct cEdit *ptr_cedit)
struct cClip* | cEdit_GetParent (struct cEdit *ptr_cedit)
void | cEdit_Hide (struct cEdit *ptr_cedit)
void | cEdit_Show (struct cEdit *ptr_cedit)
void | cEdit_Disable (struct cEdit *ptr_cedit)
void | cEdit_Enable (struct cEdit *ptr_cedit)

Detailed Description

Use a cEdit object to put a standard edit control on the Cybiko screen. cEdit controls are used to retrieve the text that users type. cEdit controls can also display text to the user.

When only displaying text to the user, choose an edit control to allow users to select text and copy it to the buffer.

See also:
Controls

Member Function Documentation

int cEdit_AppendText ( | struct cEdit * ptr_cedit,
 | char * text )

Appends text from external buffer.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
text | The text to append
Returns:
Number of characters in the text string
       #include <cywin.h>
       ...
       struct cEdit cedit;
       char   buffer[100];
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_normal,
                   CLR_LTGRAY,
                   100 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       cEdit_GetText( &cedit, buffer );
       cEdit_AppendText( &cedit, ";" );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

void cEdit_Disable ( struct cEdit * ptr_cedit )

Disables the cEdit object so that it cannot be selected.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cEdit_Enable.

void cEdit_Disconnect ( struct cEdit * ptr_cedit )

Disconnects a cEdit from its parent object.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
None
    #include <cywin.h>
    ...
    struct cBitmap cbmp;
    struct Bitmap bmp;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    // Creates a bitmap from the file "root.ico".
    Bitmap_ctor_Ex1( &bmp, "root.ico" );
    cBitmap_ctor( &cbmp, &bmp );
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Removes the object from the Cybiko screen.
    //It's the same as using the cObject_Disconnect( &cbmp ) function.
    cBitmap_Disconnect( &cbmp );
    ...
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Afterwards this function disconnects the cBitmap object automatically.
    cBitmap_dtor( &cbmp, LEAVE_MEMORY );
    Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cEdit_Enable ( struct cEdit * ptr_cedit )

Enables a cEdit object so that it may be selected.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cEdit_Disable.

char * cEdit_GetBufferPtr ( struct cEdit * ptr_cedit )

Returns a pointer to the internal buffer.

Parameters:
ptr_cedit A pointer to the initialized cEdit object.
Returns:
A pointer to a cEdit text string.
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_normal,
                   CLR_LTGRAY,
                   100 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       TRACE( "%s", cEdit_GetBufferPtr( &cedit ) );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

int cEdit_GetCursorPos ( struct cEdit * ptr_cedit )

Returns the current cursor position relative to the beginning of a piece of text.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
Resulting cursor position
       #include <cywin.h>
       ...
       struct cEdit cedit;
       int    curPos;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       // Sets the password's character limit. A password can't be longer than 8 characters.
       if ( cEdit_GetCursorPos( &cedit ) >= 8 )
       {
         cEdit_SetReadOnly( &cedit, TRUE );
         cEdit_SetCursorPos( &cedit, 0 );
       }
       ...
       curPos = cEdit_GetCursorPos( &cedit );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
cEdit_SetCursorPos.

struct cClip * cEdit_GetParent ( struct cEdit * ptr_cedit )

Returns a pointer to the cClip of the parent object.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
A pointer to the cClip of the parent object
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_GetParent( &button ) function.
    // Checks for the right parent relation.
    parent = cObject_GetParent( &button );
    if ( parent == main_module.m_process )
    {
      ...
    }
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

int cEdit_GetText ( | struct cEdit * ptr_cedit,
 | char * buffer )

Saves "text" to the external buffer.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
buffer | A string buffer
Returns:
Number of characters in the "text"
       #include <cywin.h>
       ...
       struct cEdit cedit;
       char   buffer[8];
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   oool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       // Sets the password's character limit. A password can't be longer than 8 characters.
       if ( cEdit_GetTextLength( &cedit ) >= 8 )
       {
         cEdit_SetReadOnly( &cedit, TRUE );
         cEdit_SetCursorPos( &cedit, 0 );
         cEdit_GetText( &cedit, buffer );
       }
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
cEdit_GetText_Ex, cEdit_SetText.

int cEdit_GetTextLength ( struct cEdit * ptr_cedit )

Returns the current text length (not including finishing '\0').

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
Current text length
       #include <cywin.h>
       ...
       struct cEdit cedit;
       char   buffer[8];
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       // Sets the limit on password. Password can't be larger than 8 symbols.
       if ( cEdit_GetTextLength( &cedit ) >= 8 )
       {
         cEdit_SetReadOnly( &cedit, TRUE );
         cEdit_SetCursorPos( &cedit, 0 );
         cEdit_GetText( &cedit, buffer );
       }
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
cEdit_GetText.

int cEdit_GetText_Ex ( | struct cEdit * ptr_cedit,
 | struct Output * ptr_output )

Saves "text" to the external output stream.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
ptr_output | A pointer to the initialized Output object
Returns:
Number of characters in the text string
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       struct FileOutput file_doc;
       ...
       init_module( &main_module );
       ...
       FileOutput_ctor_Ex( &file_doc, "doc.txt", TRUE );
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
         cEdit_GetText_Ex( &cedit, &file_doc );
       cEdit_dtor( &cedit, LEAVE_MEMORY );
       FileOutput_dtor( &file_doc, LEAVE_MEMORY );
See also:
cEdit_GetText.

void cEdit_Hide ( struct cEdit * ptr_cedit )

Hides a cEdit object.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cEdit_Show.

void cEdit_HighliteText ( | struct cEdit * ptr_cedit,
 | bool flag )

Sets a highlighted state.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
flag | Sets the highlighted state
Returns:
None
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
        if( cEdit_IsHighlited( &cedit ) )
            cEdit_HighliteText( &cedit, FALSE );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

bool cEdit_IsHighlited ( struct cEdit * ptr_cedit )

Highlighted state.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
TRUE if the text is highlighted
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
        if( cEdit_IsHighlited( &cedit ) )
            cEdit_HighliteText( &cedit, FALSE );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

bool cEdit_IsModified ( struct cEdit * ptr_cedit )

Checks whether the text has been modified.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
TRUE if the text was modified
       #include <cywin.h>
       ...
       struct cEdit cedit;
       char   buffer[8];
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       // Sets the password's character limit. A password can't be longer than 8 characters.
       if ( cEdit_IsModified( &cedit ) && if ( cEdit_GetTextLength( &cedit ) >= 8 )
       {
         cEdit_SetReadOnly( &cedit, TRUE );
         cEdit_SetCursorPos( &cedit, 0 );
         cEdit_GetText( &cedit, buffer );
       }
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

int cEdit_MoveCursor ( | struct cEdit * ptr_cedit,
 | int reg )

Uses one of these defined methods for moving the cursor: one line up = mc_lineup; one line down = mc_linedown; one page up = mc_pageup; one page down = mc_pagedown (the number of lines per page is defined in page_line_count).
Move to the beginning of the current line = mc_home; move to the end of the current line = mc_end.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
reg | The method of moving. See "Remarks"
Returns:
The resulting cursor position
       #include <cywin.h>
       ...
       struct cEdit cedit;
       sruct Message* ptr_message;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_normal,
                   CLR_LTGRAY,
                   100 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
       if( ( ptr_message->msgid == MSG_KEYDOWN ) &&
           ( Message_get_key_param(ptr_message)->scancode == KEY_U ))
            cEdit_MoveCursor( &cedit, mc_pageup );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
mc_lineup , mc_linedown , mc_pageup , mc_pagedown , mc_home , mc_end.

bool cEdit_Select ( struct cEdit * ptr_cedit )

Selects a cEdit object.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
TRUE if the object was selected
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the "button" object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Select( &button ) function.
    // Selects the button.
    cObject_Select( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

int cEdit_SetCursorPos ( | struct cEdit * ptr_cedit,
 | int position )

Moves the cursor to a given position relative to the beginning of a string or block of text.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
position | The new cursor position
Returns:
The resulting cursor position
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       // Sets the password's character limit. A password can't be longer than 8 characters.
       if ( cEdit_GetCursorPos( &cedit ) >= 8 )
       {
         cEdit_SetReadOnly( &cedit, TRUE );
         cEdit_SetCursorPos( &cedit, 0 );
       }
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
cEdit_GetCursorPos.

int cEdit_SetPageLineCount ( | struct cEdit * ptr_cedit,
 | int lines )

Sets the page length (number of lines to move text when using cursor pageup/down commands).

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
lines | The number of lines
Returns:
The previous page line count
       #include <cywin.h>
       ...
       struct cEdit cedit;
       sruct Message* ptr_message;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_normal,
                   CLR_LTGRAY,
                   100 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
       if( ( ptr_message->msgid == MSG_KEYDOWN ) &&
           ( Message_get_key_param(ptr_message)->scancode == KEY_U ))
       {
            // Page will contain 20 lines.
            cEdit_SetPageLineCount( &cedit, 20 );
            cEdit_MoveCursor( &cedit, mc_pageup );
       }
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

bool cEdit_SetReadOnly ( | struct cEdit * ptr_cedit,
 | bool state )

Sets a read-only state.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
state | TRUE if the read-only state needs to be set
Returns:
The previous read-only state
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       // Sets the password's character limit. A password can't be longer than 8 symbols.
       if ( cEdit_GetCursorPos( &cedit ) >= 8 )
            cEdit_SetReadOnly( &cedit, TRUE );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

int cEdit_SetText ( | struct cEdit * ptr_cedit,
 | char * text )

Loads text from an external buffer.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
text | The text to set
Returns:
The number of characters in the text string
       #include <cywin.h>
       ...
       struct cEdit cedit;
       int    numSimb;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_normal,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       numSimb = cEdit_SetText( &cedit, "This text will be loaded" );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
cEdit_SetText_Ex, cEdit_GetText.

int cEdit_SetText_Ex ( | struct cEdit * ptr_cedit,
 | struct Input * ptr_input )

Loads text from an external input stream.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
ptr_input | A pointer to the initialized Input object
Returns:
The number of characters in the text string
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       struct FileInput file_doc;
       ...
       init_module( &main_module );
       ...
       FileInput_ctor_Ex( &file_doc, "doc.txt" );
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       cEdit_SetText_Ex( &cedit, &file_doc );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
       FileInput_dtor( &file_doc, LEAVE_MEMORY );
See also:
cEdit_SetText.

void cEdit_Show ( struct cEdit * ptr_cedit )

Shows a cEdit object.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cEdit_Hide.

struct cEdit * cEdit_ctor ( | struct cEdit * ptr_cedit,
 | struct Font * ptr_cfont,
 | int buffer_size,
 | int style,
 | color_t color,
 | int width )

Constructor.

Parameters:
ptr_cedit | A pointer to the cEdit struct
ptr_cfont | The font for drawing text
buffer_size | Maximum text length (not including finishing '\0')
style | Style state bits
color | Text color.
width | Width of the edit window (-1 means single-line style with unlimited width and horizontal scrolling)
Returns:
A pointer to the initialized cEdit object.
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
cEdit_dtor.

void cEdit_dtor ( | struct cEdit * ptr_cedit,
 | int memory_flag )

Destructor.
Deletes an object.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if the object was static or allocated in a stack
Returns:
None
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );
See also:
cEdit_ctor, FREE_MEMORY, LEAVE_MEMORY.

bool cEdit_proc ( | struct cEdit * ptr_cedit,
 | struct Message * ptr_message )

Message-processing function.

Parameters:
ptr_cedit | A pointer to the initialized cEdit object
ptr_message | A pointer to the Message struct
Returns:
TRUE if the message was processed
       #include <cywin.h>
       ...
       struct cEdit cedit;
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY,
       //                         CLR_WHITE, CLR_BLACK.
       cEdit_ctor( &cedit,
                   cool_normal_font,
                   100,
                   es_password,
                   CLR_LTGRAY,
                   -1 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cedit, 10, 40 );
       ...
       ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
       // Processes the messages that the cEdit control manages.
       cEdit_proc( &cedit, ptr_message );
       ...
       cEdit_dtor( &cedit, LEAVE_MEMORY );

void cEdit_update ( struct cEdit * ptr_cedit )

Updates a cEdit object.

Parameters:
ptr_cedit A pointer to the initialized cEdit object
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the "button" object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    cWinApp_clear_screen();
    // It's the same as using the cButton_update( &button ) function.
    // Redraws the button.
    cObject_update( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );


cItem Struct Reference

Inheritance diagram for cItem

Collaboration diagram for cItem:

Public Methods
struct cItem* | cItem_ctor (struct cItem *ptr_citem, int width, char *title_name, bool submenu, char *right_text, struct Bitmap *ptr_bitmap)
void | cItem_dtor (struct cItem *ptr_citem, int memory_flag)
char* | cItem_GetTitle (struct cItem *ptr_citem)
bool | cItem_proc (struct cItem *ptr_citem, struct Message *ptr_message)
void | cItem_Disconnect (struct cItem *ptr_citem)
bool | cItem_Select (struct cItem *ptr_citem)
void | cItem_update (struct cItem *ptr_citem)
struct cClip* | cItem_GetParent (struct cItem *ptr_citem)
void | cItem_Hide (struct cItem *ptr_citem)
void | cItem_Show (struct cItem *ptr_citem)
void | cItem_Disable (struct cItem *ptr_citem)
void | cItem_Enable (struct cItem *ptr_citem)

Detailed Description

This structure implements methods for working with simple units of the list, such as a text string. It might have an icon on the left and/or an additional text on the right.

You must call the cItem_ctor function before use and the cItem_dtor function after use.

See also:
Controls

Member Function Documentation

void cItem_Disable ( struct cItem * ptr_citem )

Disables a cItem object so that it cannot be selected.

Parameters:
ptr_citem A pointer to a cItem object
Returns:
None
See also:
cItem_Enable.

void cItem_Disconnect ( struct cItem * ptr_citem )

Disconnects a cItem from its parent object.

Parameters:
ptr_citem A pointer to a cItem object
Returns:
None

void cItem_Enable ( struct cItem * ptr_citem )

Enables a cItem object so that it may be selected.

Parameters:
ptr_citem A pointer to a cItem object
Returns:
None
See also:
cItem_Disable.

struct cClip * cItem_GetParent ( struct cItem * ptr_citem )

Returns a pointer to the parent object.

Parameters:
ptr_citem A pointer to a cItem object
Returns:
A pointer to the parent object

char * cItem_GetTitle ( struct cItem * ptr_citem )

Returns the item's title.

Parameters:
ptr_citem A pointer to the initialized cItem object
Returns:
The item's title
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item[3];
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item[index] = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item + index, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item + index );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     for( index = 0; index < 3; index++ )
     {
        TRACE( "%s - item #%d ", cItem_GetTitle( ptr_menu_item + index), index );
     }
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }

void cItem_Hide ( struct cItem * ptr_citem )

Hides a cItem object.

Parameters:
ptr_citem A pointer to a cItem object
Returns:
None
See also:
cItem_Show.

bool cItem_Select ( struct cItem * ptr_citem )

Selects a cItem object.

Parameters:
ptr_citem A pointer to a cItem object
Returns:
TRUE if the object was selected

void cItem_Show ( struct cItem * ptr_citem )

Shows a cItem object.

Parameters:
ptr_citem A pointer to a cItem object.
Returns:
None
See also:
cItem_Hide.

struct cItem * cItem_ctor ( | struct cItem * ptr_citem,
 | int width,
 | char * title_name,
 | bool submenu,
 | char * right_text,
 | struct Bitmap * ptr_bitmap )

Constructor.
Initialize the cItem object.

Parameters:
ptr_citem | A pointer to the cItem struct
width | Item's width (in pixels)
title_name | Item's title
submenu | Determines whether there is a submenu
right_text | Creates an additional text area on the right
ptr_bitmap | Creates pointer to the icon bitmap
Returns:
A pointer to the initialized cItem object
   #include <cywin.h>
     ...
   {
     struct cList menu;
     struct BitmapSequence menu_icons;
     struct module_t main_module;
     struct Message* ptr_message;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "CYBIKO",
                                           "Microsoft",
                                           "Ford"
                                          };
     static const char* sz_right_text[3] = {
                                            "Yang",
                                            "Gates",
                                            "Ford"
                                           };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     BitmapSequence_ctor_Ex( &menu_icons , "logos.pic");
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item,
                   100,
                   sz_menu_text[index],
                   FALSE,
                   sz_right_text[index],
                   BitmapSeqence_get_bitmap( &menu_icons, index ) );
       cList_AddItem( &menu, ptr_menu_item );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
     BitmapSequence_dtor( &menu_icons, LEAVE_MEMORY );
   }

void cItem_dtor ( | struct cItem * ptr_citem,
 | int memory_flag )

Destructor.
Deletes a cItem object.

Parameters:
ptr_citem | A pointer to the initialized cItem object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item[3];
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item[index] = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item + index, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item + index );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // "High Score"  will be removed from the list.
     cList_RemItem( &menu, ptr_menu_item + 1 );
     cItem_dtor( ptr_menu_item + 1 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cItem_proc ( | struct cItem * ptr_citem,
 | struct Message * ptr_message )

Message-processing function.

Parameters:
ptr_citem | A pointer to a cList object
ptr_message | A pointer to a Message.
Returns:
TRUE if the message was processed.
   #include <cywin.h>
     ...
     struct module_t main_module;
     struct Message* ptr_message;
     struct cItem menu_item;
     ...
     init_module( &main_module );
     ...
     cItem_ctor( &menu_item, 100, "Item", FALSE, NULL, NULL );
     // Puts the cItem object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu_item, 10, 40 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     // cItem will be redrawn automatically now.
     cItem_proc( &menu_item, ptr_message );
     ...
     cItem_dtor( &menu_item, LEAVE_MEMORY );

void cItem_update ( struct cItem * ptr_citem )

Updates a cItem object.

Parameters:
ptr_citem A pointer to a cItem object
Returns:
None


cList Struct Reference

Inheritance diagram for cList

Collaboration diagram for cList:

Public Methods
struct cList* | cList_ctor (struct cList *ptr_clist, int width)
void | cList_dtor (struct cList *ptr_clist, int memory_flag)
void | cList_AddItem (struct cList *ptr_clist, struct cObject *ptr_cobject)
void | cList_AddItem_Ex (struct cList *ptr_clist, struct cObject *ptr_cobject, int number_items)
void | cList_RemItem (struct cList *ptr_clist, struct cObject *ptr_cobject)
bool | cList_proc (struct cList *ptr_clist, struct Message *ptr_message)
int | cList_Sel (struct cList *ptr_clist)
void | cList_Disconnect (struct cList *ptr_clist)
bool | cList_Select (struct cList *ptr_clist)
void | cList_update (struct cList *ptr_clist)
struct cClip* | cList_GetParent (struct cList *ptr_clist)
void | cList_Hide (struct cList *ptr_clist)
void | cList_Show (struct cList *ptr_clist)
void | cList_Disable (struct cList *ptr_clist)
void | cList_Enable (struct cList *ptr_clist)
void | cList_AddObj (struct cList *ptr_clist, struct cObject *ptr_object, int x, int y)
void | cList_InsObj (struct cList *ptr_clist, struct cObject *ptr_object, int x, int y, int index)
void | cList_RemObj (struct cClip *ptr_clist, struct cObject *ptr_object)
bool | cList_SelectFirst (struct cList *ptr_clist)
bool | cList_SelectPrev (struct cList *ptr_clist, bool round)
bool | cList_SelectNext (struct cList *ptr_clist, bool round)
void | cList_Scroll (struct cList *ptr_clist, struct rect_t *rectangle)
void | cList_Scroll_Ex (struct cList *ptr_clist, int x, int y)
void | cList_SendScroll (struct cList *ptr_clist)
int | cList_GetShifty (struct cList *ptr_clist)
int | cList_GetShiftx (struct cList *ptr_clist)
int | cList_GetCount (struct cList *ptr_clist)
struct cObject* | cList_get_by_index (struct cList *ptr_clist, int index)
int | cList_FindObj (struct cList *ptr_clist, struct cObject *ptr_object)
struct cObject* | cList_GetSelectedObject (struct cList *ptr_clist)

Detailed Description

This structure implements methods for working with a list and a menu. A cList object is a container for cItem, cXItem and cSItem objects.

To add these objects to a list, use the cList_AddItem function. To remove objects from a list or a menu use the cList_RemItem function.

When a message comes in, process it using the cList_proc function.

You must call the cList_ctor function before use and the cList_dtor function after use.

See also:
Controls

Member Function Documentation

void cList_AddItem ( | struct cList * ptr_clist,
 | struct cObject * ptr_cobject )

Adds an object (a cItem object for instance) to a cList object.

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_cobject | A pointer to the initialized cObject
Returns:
None
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
cList_AddItem_Ex, cList_RemItem.

void cList_AddItem_Ex ( | struct cList * ptr_clist,
 | struct cObject * ptr_cobject,
 | int number_items )

The extended version of the cList_AddItem function.
Adds an object to a cList object in a specified position.

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_cobject | A pointer to the initialized cObject
number_items | The zero based position in the cList object
Returns:
None
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ));
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item, index );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
cList_AddItem, cList_RemItem.

void cList_AddObj ( | struct cList * ptr_clist,
 | struct cObject * ptr_object,
 | int x,
 | int y )

Adds an object to the cList in position (x, y).

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_object | A pointer to the initialized cObject object
x | x-coordinate of the new object
y | y-coordinate of the new object
Returns:
None

void cList_Disable ( struct cList * ptr_clist )

Disables a cList object so that it cannot be selected.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
None
See also:
cList_Enable.

void cList_Disconnect ( struct cList * ptr_clist )

Disconnects a cList from its parent object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
None

void cList_Enable ( struct cList * ptr_clist )

Enables a cList object so that it may be selected.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
None
See also:
cList_Disable.

int cList_FindObj ( | struct cList * ptr_clist,
 | struct cObject * ptr_object )

Returns a child object's index in the cList (or -1).

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_object | A pointer to the needed cObject
Returns:
The child's object's index in the cList (or -1)

int cList_GetCount ( struct cList * ptr_clist )

Returns a count of child objects.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
The child objects count

struct cClip * cList_GetParent ( struct cList * ptr_clist )

Returns a pointer to the cClip of the parent object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
A pointer to the cClip of the parent object

struct cObject * cList_GetSelectedObject ( struct cList * ptr_clist )

Returns the currently selected object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
A pointer to the currently selected object
    #include <cywin.h>
     ...
     struct cItem* ptr_selected_item;
     ...
     // Retrieves the pointer to the list item currently selected
     ptr_selected_item = cList_GetSelectedObject( ptr_list_object );
     ...

int cList_GetShiftx ( struct cList * ptr_clist )

Returns the 'x' coordinate shift (as a result of scrolling).

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
'x' coordinate shift (as a result of scrolling)

int cList_GetShifty ( struct cList * ptr_clist )

Returns the 'y' coordinate shift (as a result of scrolling).

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
'y' coordinate shift (as a result of scrolling).

void cList_Hide ( struct cList * ptr_clist )

Hides a cList object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
None
   #include <cybiko.h>
   ...
   struct cList main_menu;
   ...
   case MSG_LOSTFOCUS: // Application has lost focus
        ...
        cList_Hide( &main_menu );
        break;
   ...
   case MSG_GOTFOCUS: // Application has focus
        ...
        cList_Show( &main_menu );
        break;
   ...
See also:
cList_Show.

void cList_InsObj ( | struct cList * ptr_clist,
 | struct cObject * ptr_object,
 | int x,
 | int y,
 | int index )

Adds an object to the cList in position ( x, y ) with a z-position index (maximal index is on the top).

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_object | A pointer to the initialized cObject object
x | x-coordinate of the new object
y | y-coordinate of the new object
index | z-position of the new object
Returns:
None

void cList_RemItem ( | struct cList * ptr_clist,
 | struct cObject * ptr_cobject )

Removes an object from a cList object.

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_cobject | A pointer to the initialized cObject
Returns:
None
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item[3];
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item[index] = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item + index, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item + index );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // "High Score"  will be removed from the list.
     cList_RemItem( &menu, ptr_menu_item + 1 );
     cItem_dtor( ptr_menu_item + 1 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
cList_AddItem, cList_AddItem_Ex.

void cList_RemObj ( | struct cClip * ptr_clist,
 | struct cObject * ptr_object )

Removes an object from a cList.

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_object | A pointer to the initialized cObject object
Returns:
None

void cList_Scroll ( | struct cList * ptr_clist,
 | struct rect_t * rectangle )

Scrolls a cList to make a rectangle visible.
Provides minimal scrolling.

Parameters:
ptr_clist | A pointer to the initialized cList object
rectangle | A pointer to the initialized rect_t structure
Returns:
None
See also:
cList_Scroll_Ex.

void cList_Scroll_Ex ( | struct cList * ptr_clist,
 | int x,
 | int y )

Scrolls a cList by (x, y), but cannot exceed the child's boundaries.

Parameters:
ptr_clist | A pointer to the initialized cList object
x | "x" coordinate shift
y | "y" coordinate shift
Returns:
None
See also:
cList_Scroll.

int cList_Sel ( struct cList * ptr_clist )

Returns the index of the currently selected object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
The index of the currently selected object
   #include <cywin.h>
     ...
   {
     struct cList menu;
     struct module_t main_module;
     struct Message* ptr_message;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       if( Message_get_key_param( ptr_message )->scancode == KEY_ENTER )
       {
         switch ( cList_Sel( &menu ) )
         {
           case 0:
           ...
         }
       }
       //  Now we can select menu items using up and down arrows.
       cList_proc( &menu, ptr_message );
     }
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }

bool cList_Select ( struct cList * ptr_clist )

Selects a cList object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
TRUE if the cList object was selected

bool cList_SelectFirst ( struct cList * ptr_clist )

Selects the first object in the cList.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
FALSE if the function failed

bool cList_SelectNext ( | struct cList * ptr_clist,
 | bool round )

Selects the next object in the cList.

Parameters:
ptr_clist | A pointer to the initialized cList object
round | TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed

bool cList_SelectPrev ( | struct cList * ptr_clist,
 | bool round )

Selects the previous object in the cList.

Parameters:
ptr_clist | A pointer to the initialized cList object
round | TRUE if you need to select the last object after selecting the first
Returns:
FALSE if function failed.

void cList_SendScroll ( struct cList * ptr_clist )

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
None

void cList_Show ( struct cList * ptr_clist )

Shows a cList object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
None
   #include <cybiko.h>
   ...
   struct cList main_menu;
   ...
   case MSG_LOSTFOCUS: // Application has lost focus
        ...
        cList_Hide( &main_menu );
        break;
   ...
   case MSG_GOTFOCUS: // Application has focus
        ...
        cList_Show( &main_menu );
        break;
   ...
See also:
cList_Hide.

struct cList * cList_ctor ( | struct cList * ptr_clist,
 | int width )

Constructor.
Creates an empty cList object.

Parameters:
ptr_clist | A pointer to the cList structure
width | The width of a cList object.
Returns:
A pointer to the initialized cList object
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {"Start",
                              "High Score",
                              "Exit"
                              };
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ));
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item);
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }

void cList_dtor ( | struct cList * ptr_clist,
 | int memory_flag )

Destructor.
Deletes the cList object and all child objects (if any).

Parameters:
ptr_clist | A pointer to the initialized cList object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if the object was static or allocated in a stack
Returns:
None
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 ) ;
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ));
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item);
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct cObject * cList_get_by_index ( | struct cList * ptr_clist,
 | int index )

Returns object index (or NULL).

Parameters:
ptr_clist | A pointer to the initialized cList object
index | The index of the object in cList
Returns:
The object's index (or NULL)

bool cList_proc ( | struct cList * ptr_clist,
 | struct Message * ptr_message )

Message-processing function.

Parameters:
ptr_clist | A pointer to the initialized cList object
ptr_message | A pointer to the Message structure
Returns:
TRUE if the message was processed
   #include <cywin.h>
     ...
   {
     struct cList menu;
     struct module_t main_module;
     struct Message* ptr_message;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       //  Now we can select menu items using up and down arrows.
       cList_proc( &menu, ptr_message );
     }
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }

void cList_update ( struct cList * ptr_clist )

Updates a cList object.

Parameters:
ptr_clist A pointer to the initialized cList object
Returns:
None
   #include <cybiko.h>
   ...
   struct cList main_menu;
   ...
   // Redraws the menu object and the screen
   cList_update( &main_menu );
   ...


cProgressBar Struct Reference

Inheritance diagram for cProgressBar

Collaboration diagram for cProgressBar:

Public Methods
struct cProgressBar* | cProgressBar_ctor (struct cProgressBar *, int, int, int, struct Font *, color_t, color_t, int)
void | cProgressBar_dtor (struct cProgressBar *, int)
void | cProgressBar_SetCurrentPos (struct cProgressBar *, int)
bool | cProgressBar_proc (struct cProgressBar *ptr_cprogress_bar, struct Message *ptr_message)
void | cProgressBar_Disconnect (struct cProgressBar *ptr_cprogress_bar)
bool | cProgressBar_Select (struct cProgressBar *ptr_cprogress_bar)
void | cProgressBar_update (struct cProgressBar *ptr_cprogress_bar)
struct cClip* | cProgressBar_GetParent (struct cProgressBar *ptr_cprogress_bar)
void | cProgressBar_Hide (struct cProgressBar *ptr_cprogress_bar)
void | cProgressBar_Show (struct cProgressBar *ptr_cprogress_bar)
void | cProgressBar_Disable (struct cProgressBar *ptr_cprogress_bar)
void | cProgressBar_Enable (struct cProgressBar *ptr_cprogress_bar)

Detailed Description

Use cProgressBar to add a progress bar to your application. Progress bars provide users with visual feedback about the progress of a procedure within an application. As the procedure progresses, the rectangular progress bar gradually fills from left to right with the system highlight color.

See also:
Controls

Member Function Documentation

void cProgressBar_Disable ( struct cProgressBar * ptr_cprogress_bar )

Disables a cProgressBar object so that it cannot be selected.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cProgressBar_Enable.

void cProgressBar_Disconnect ( struct cProgressBar * ptr_cprogress_bar )

Disconnects a cProgressBar from it's parent object.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure.
Returns:
None
    #include <cywin.h>
    ...
    struct cBitmap cbmp;
    struct Bitmap bmp;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    // Creates a bitmap from the file "root.ico".
    Bitmap_ctor_Ex1( &bmp, "root.ico" );
    cBitmap_ctor( &cbmp, &bmp );
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Removes the object from the Cybiko screen. It's the same as using the cObject_Disconnect( &cbmp ) function.
    cBitmap_Disconnect( &cbmp );
    ...
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    // Afterwards this function disconnects the cBitmap object automatically.
    cBitmap_dtor( &cbmp, LEAVE_MEMORY );
    Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cProgressBar_Enable ( struct cProgressBar * ptr_cprogress_bar )

Enables for selection cProgressBar object.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure.
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Disable( &button ) function.
    // Now the user can't use this object.
    cObject_Disable( &button )
    ...
    // It's the same as using the cButton_Enable( &button ) function.
    // Now the user can use this object again.
    cObject_Enable( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cProgressBar_Disable.

struct cClip * cProgressBar_GetParent ( struct cProgressBar * ptr_cprogress_bar )

Returns a pointer to the cClip of the parent object.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure
Returns:
A pointer to the cClip of the parent object
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_GetParent( &button ) function.
    // Checks for the right parent relation.
    parent = cObject_GetParent( &button );
    if ( parent == main_module.m_process )
    {
      ...
    }
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

void cProgressBar_Hide ( struct cProgressBar * ptr_cprogress_bar )

Hides a cProgressBar object.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cProgressBar_Show.

bool cProgressBar_Select ( struct cProgressBar * ptr_cprogress_bar )

Selects a cProgressBar object.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure
Returns:
TRUE if the progress bar is selected
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Select( &button ) function.
    // Selects the button.
    cObject_Select( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );

void cProgressBar_SetCurrentPos ( | struct cProgressBar * ptr_cpb,
 | int cur_pos )

Sets the current bar position and updates the object.

Parameters:
ptr_cpb | A pointer to the initialized cProgressBar object
cur_pos | Should be between min_pos and max_pos (see cProgressBar_ctor). Progress status depends on a linear shift in position. Min_pos sets progress status to 0%, max_pos - to 100%
Returns:
None
       #include <cywin.h>
       {
       ...
       struct cProgressBar cprogr;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cProgressBar_ctor( &cprogr,
                          100,
                          0,
                          100,
                          cool_normal_font,
                          CLR_WHITE,
                          CLR_BLACK,
                          20 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cprogr, 10, 40 );
       ...
       for( int i=0; i<100; i++ )
       {
          ...
          cProgressBar_SetCurrentPos( &cprogr, i );
          ...
       }
       ...
       cProgressBar_dtor( &cedit, LEAVE_MEMORY );\
       }
See also:
cProgressBar_ctor, FREE_MEMORY, LEAVE_MEMORY.

void cProgressBar_Show ( struct cProgressBar * ptr_cprogress_bar )

Shows a cProgressBar object.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    struct cClip* parent;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    // It's the same as using the cButton_Hide( &button ) function.
    cObject_Hide( &button );
    ...
    // It's the same as using the cButton_Show( &button ) function.
    cObject_Show( &button );
    ...
    cButton_dtor( &button, LEAVE_MEMORY );
See also:
cProgressBar_Hide.

struct cProgressBar * cProgressBar_ctor ( | struct cProgressBar * ptr_cpb,
 | int width,
 | int min_pos,
 | int max_pos,
 | struct Font * txtfont,
 | color_t color,
 | color_t back_color,
 | int height )

Constructor.

Parameters:
ptr_cpb | A pointer to the cProgressBar struct
width | The total width of the object. Maximal length of the progress bar itself will be width - 4 because of the frame in which it is enclosed
min_pos | The value that should be passed via SetCurrentPos to set the progress status to 0%
max_pos | The value that should be passed via SetCurrentPos to set the progress status to 100%
txtfont | The font for the progress status text output
color | Main object's color
back_color | Background color
height | The total height with frame. Should not be set below default value height = 16
Returns:
A pointer to the initialized cProgressBar object
       #include <cywin.h>
       ...
       struct cProgressBar cprogr;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cProgressBar_ctor( &cprogr,
                          100,
                          0,
                          100,
                          cool_normal_font,
                          CLR_WHITE,
                          CLR_BLACK,
                          20 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cprogr, 10, 40 );
       ...
       cProgressBar_dtor( &cedit, LEAVE_MEMORY );
See also:
cProgressBar_dtor.

void cProgressBar_dtor ( | struct cProgressBar * ptr_cpb,
 | int memory_flag )

Destructor.
Deletes an object.

Parameters:
ptr_cpb | A pointer to the initialized cProgressBar object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if the object was static or allocated in a stack
Returns:
None
       #include <cywin.h>
       ...
       struct cProgressBar cprogr;
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       // The color value may be: CLR_LTGRAY, CLR_BKGRAY, CLR_WHITE, CLR_BLACK.
       cProgressBar_ctor( &cprogr,
                          100,
                          0,
                          100,
                          cool_normal_font,
                          CLR_WHITE,
                          CLR_BLACK,
                          20 );
       // Puts the cBitmap object on the Cybiko screen.
       cWinApp_AddObj( main_module.m_process, &cprogr, 10, 40 );
       ...
       cProgressBar_dtor( &cedit, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cProgressBar_proc ( | struct cProgressBar * ptr_cprogress_bar,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cprogress_bar | A pointer to the initialized cProgressBar structure
ptr_message | A pointer to the processed message
Returns:
TRUE, if the message was processed
    #include <cywin.h>
    ...
    struct cBitmap cbmp;
    struct Bitmap bmp;
    struct module_t main_module;
    struct Message* ptr_message;
    ...
    init_module( &main_module );
    ...
    // Creates a bitmap from the file "root.ico".
    Bitmap_ctor_Ex1( &bmp, "root.ico" );
    cBitmap_ctor( &cbmp, &bmp );
    // Puts the cBitmap object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &cbmp, 10, 40 );
    ...
    ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
    // It's the same as using the cObject_proc( &cbmp, ptr_message ) function.
    // Processes the messages that the cBitmap control manages.
    cBitmap_proc( &cbmp, ptr_message );
    ...
    // Afterwards this function disconnects the cBitmap object automatically.
    cBitmap_dtor( &cbmp, LEAVE_MEMORY );
    Bitmap_dtor( &bmp, LEAVE_MEMORY );

void cProgressBar_update ( struct cProgressBar * ptr_cprogress_bar )

Updates a cProgressBar object.
Sends a signal to the system, that the object must be redrawn. After you change the state of an object, you must call this function to redraw your object.

Parameters:
ptr_cprogress_bar A pointer to the initialized cProgressBar structure
Returns:
None
    #include <cywin.h>
    ...
    struct cButton button;
    struct module_t main_module;
    ...
    init_module( &main_module );
    ...
    cButton_ctor( &button, "Button text", mrOk );
    // Puts the 'button' object on the Cybiko screen.
    cWinApp_AddObj( main_module.m_process, &button, 20, 50 );
    ...
    cWinApp_clear_screen();
    // It's the same as using the cButton_update( &button ) function.
    // Redraws the button.
    cObject_update( &button )
    ...
    cButton_dtor( &button, LEAVE_MEMORY );


cSItem Struct Reference

Inheritance diagram for cSItem

Collaboration diagram for cSItem:

Public Methods
struct cSItem* | cSItem_ctor (struct cSItem *ptr_csitem, int w, char *title, struct Bitmap *ptr_bitmap)
void | cSItem_dtor (struct cSItem *ptr_csitem, int memory_flag)
void | cSItem_Disconnect (struct cSItem *ptr_csitem)
bool | cSItem_Select (struct cSItem *ptr_csitem)
void | cSItem_update (struct cSItem *ptr_csitem)
struct cClip* | cSItem_GetParent (struct cSItem *ptr_csitem)
void | cSItem_Hide (struct cSItem *ptr_csitem)
void | cSItem_Show (struct cSItem *ptr_csitem)
void | cSItem_Disable (struct cSItem *ptr_csitem)
void | cSItem_Enable (struct cSItem *ptr_csitem)
char* | cSItem_GetTitle (struct cSItem *ptr_csitem)
bool | cSItem_proc (struct cSItem *ptr_csitem, struct Message *ptr_message)

Detailed Description

A cSItem object might have an icon on the left and/or additional text on the right It is possible to input text into the field on the right, but only numerical data. For more information see the cItem structure definition.

You must call the cSItem_ctor function before use and the cSItem_dtor function after use.

See also:
Controls

Member Function Documentation

void cSItem_Disable ( struct cSItem * ptr_csitem )

Disables a cSItem object so that it cannot be selected.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
None
See also:
cSItem_Enable.

void cSItem_Disconnect ( struct cSItem * ptr_csitem )

Disconnects a cSItem from its parent object.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
None

void cSItem_Enable ( struct cSItem * ptr_csitem )

Enables a cSItem object so that it may be selected.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
None
See also:
cSItem_Disable.

struct cClip * cSItem_GetParent ( struct cSItem * ptr_csitem )

Returns a pointer to the parent object.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
A pointer to the parent object

char * cSItem_GetTitle ( struct cSItem * ptr_csitem )

Returns the item's title.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
The item's title

void cSItem_Hide ( struct cSItem * ptr_csitem )

Hides a cSItem object.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
None
See also:
cSItem_Show.

bool cSItem_Select ( struct cSItem * ptr_csitem )

Selects a cSItem object.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
TRUE if the object was selected

void cSItem_Show ( struct cSItem * ptr_csitem )

Shows a cSItem object.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
None
See also:
cSItem_Hide.

struct cSItem * cSItem_ctor ( | struct cSItem * ptr_csitem,
 | int w,
 | char * title,
 | struct Bitmap * ptr_bitmap )

Constructor.
Creates an empty cSItem object.

Parameters:
ptr_csitem | A pointer to a cSItem structure
w | Item's width in pixels
title | Title string
ptr_bitmap | Creates a pointer to the icon bitmap
Returns:
A pointer to the initialized cSItem object
   #include <cywin.h>
     ...
   {
     char   buf[15];
     struct BitmapSequence * ptr_bmps = (BitmapSequence* ) malloc( sizeof( struct BitmapSequence ) );
     struct cList * ptr_clist = (cList* )malloc( sizeof( cList ) );
     struct cSItem * ptr_csitem = (cSItem* )malloc( sizeof( cSItem ) );
     ...
     BitmapSequence_ctor_Ex( ptr_bmps,"gfx.pic" );
     cList_ctor( ptr_clist, 80 );
     ...
     for ( int i=1; i<=5; i++ )
     {
       sprintf( buf, "menu item %d", i );
       cSItem_ctor( ptr_csitem, LCD_WIDTH, buf, BitmapSequence_get_bitmap( ptr_bmps, i-1 ) );
       cList_AddItem( ptr_clist, ptr_csitem );
     }
     ...
     cSItem_dtor( ptr_csitem, FREE_MEMORY );
     cList_dtor( ptr_clist, FREE_MEMORY );
     BitmapSequence_dtor( ptr_bmps, FREE_MEMORY );
   }

void cSItem_dtor ( | struct cSItem * ptr_csitem,
 | int memory_flag )

Destructor.
Deletes a cSItem object.

Parameters:
ptr_csitem | A pointer to the initialized cSItem object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
   #include <cywin.h>
     ...
   {
     char   buf[15];
     struct BitmapSequence * ptr_bmps = (BitmapSequence* ) malloc( sizeof( struct BitmapSequence ) );
     struct cList * ptr_clist = (cList* )malloc( sizeof( cList ) );
     struct cSItem * ptr_csitem = (cSItem* )malloc( sizeof( cSItem ) );
     ...
     BitmapSequence_ctor_Ex( ptr_bmps,"gfx.pic" );
     cList_ctor( ptr_clist, 80 );
     ...
     for ( int i=1; i<=5; i++ )
     {
       sprintf( buf, "menu item %d", i );
       cSItem_ctor( ptr_csitem, LCD_WIDTH, buf, BitmapSequence_get_bitmap( ptr_bmps, i-1 ) );
       cList_AddItem( ptr_clist, ptr_csitem );
     }
     ...
     cSItem_dtor( ptr_csitem, FREE_MEMORY );
     cList_dtor( ptr_clist, FREE_MEMORY );
     BitmapSequence_dtor( ptr_bmps, FREE_MEMORY );
   }
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cSItem_proc ( | struct cSItem * ptr_csitem,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_csitem | A pointer to a cSItem object
ptr_message | A pointer to a Message
Returns:
TRUE if the message was processed

void cSItem_update ( struct cSItem * ptr_csitem )

Updates a cSItem object.

Parameters:
ptr_csitem A pointer to a cSItem object
Returns:
None


cText Struct Reference

Inheritance diagram for cText

Collaboration diagram for cText:

Public Methods
struct cText* | cText_ctor (struct cText *ptr_text, char *text, struct Font *ptr_font, color_t color)
void | cText_dtor (struct cText *ptr_text, int memory_flag)
void | cText_SetText (struct cText *ptr_text, char *text)
bool | cText_proc (struct cText *ptr_text, struct Message *ptr_message)
void | cText_Disconnect (struct cText *ptr_text)
bool | cText_Select (struct cText *ptr_text)
void | cText_update (struct cText *ptr_text)
struct cClip* | cText_GetParent (struct cText *ptr_text)
void | cText_Hide (struct cText *ptr_text)
void | cText_Show (struct cText *ptr_text)
void | cText_Disable (struct cText *ptr_text)
void | cText_Enable (struct cText *ptr_text)

Detailed Description

A static, transparent text line. Use this structure to place text on the Cybiko computer's screen.

To place a cText object created by the cText_ctor function onto the Cybiko screen, use the cWinApp_AddObj function. If you want to replace the onscreen text, you should first clear it with the cWinApp_clear_screen function. Then use the cText_SetText function to place new text.

You must call the cText_ctor function before use and the cText_dtor function after use.

See also:
Controls , cWinApp_AddObj , cWinApp_clear_screen

Member Function Documentation

void cText_Disable ( struct cText * ptr_text )

Disables a cText object so that it cannot be selected.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
None
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     // Now the user can't use this object
     cText_Disable (&text);
     ...
     // Now the user can use this object again
     cText_Enable (&text);
     ...
     cText_dtor( &text, LEAVE_MEMORY );
See also:
cText_Enable.

void cText_Disconnect ( struct cText * ptr_text )

Disconnects a cText object from its parent object.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
None
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     // Removes the object from the Cybiko screen.
     cText_Disconnect( &text);
     ...
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     // Afterwards this function disconnects the cText object automatically
     cText_dtor( &text, LEAVE_MEMORY );

void cText_Enable ( struct cText * ptr_text )

Enables a cText object so that it may be selected.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
None
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     // Now the user can't use this object
     cText_Disable (&text);
     ...
     // Now the user can use this object again
     cText_Enable (&text);
     ...
     cText_dtor( &text, LEAVE_MEMORY );
See also:
cText_Disable.

struct cClip * cText_GetParent ( struct cText * ptr_text )

Returns a pointer to the parent object.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
A pointer to the parent object
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     struct cClip *parent;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     parent = cText_GetParent( &text );
     if ( parent == main_module.m_process )
     {
     }
     ...
     cText_dtor( &text, LEAVE_MEMORY );

void cText_Hide ( struct cText * ptr_text )

Hides a cText object.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
None
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     cText_Hide (&text);
      ...
     cText_Show (&text);
     ...
     cText_dtor( &text, LEAVE_MEMORY );
See also:
cText_Show.

bool cText_Select ( struct cText * ptr_text )

Selects a cText object.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
TRUE if the object was selected
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     cText_Select(&text)
     ...
     cText_dtor( &text, LEAVE_MEMORY );

void cText_SetText ( | struct cText * ptr_text,
 | char * text )

Sets a new text line.

Parameters:
ptr_text | A pointer to the initialized cText object
text | A new text string
Returns:
None
   #include <cywin.h>
     ...
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     ...
     cWinApp_clear_screen();
     cText_SetText( &text, "Another text" );
     ...
     cText_dtor( &text, LEAVE_MEMORY );

void cText_Show ( struct cText * ptr_text )

Shows a cText object.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
None
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     cText_Hide (&text);
     ...
     cText_Show (&text);
     ...
     cText_dtor( &text, LEAVE_MEMORY );
See also:
cText_Hide.

struct cText * cText_ctor ( | struct cText * ptr_text,
 | char * text,
 | struct Font * ptr_font,
 | color_t color )

Initializes a cText object.

Parameters:
ptr_text | A pointer to a cText object
text | A text string
ptr_font | A pointer to the structure of the font to use
color | The text's color
Returns:
A pointer to the initialized cText object
   #include <cywin.h>
     ...
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     ...
     cText_dtor( &text, LEAVE_MEMORY );

void cText_dtor ( | struct cText * ptr_text,
 | int memory_flag )

Deletes a cText object.

Parameters:
ptr_text | is a pointer to a cText object.
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
   #include <cywin.h>
     ...
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     ...
     cText_dtor( &text, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cText_proc ( | struct cText * ptr_text,
 | struct Message * ptr_message )

The message-processing function.

Parameters:
ptr_text | A pointer to the initialized cText object
ptr_message | A pointer to the processed message
Returns:
TRUE if the message was processed.

void cText_update ( struct cText * ptr_text )

Updates a cText object.

Parameters:
ptr_text A pointer to the initialized cText object
Returns:
None
   #include <cywin.h>
     struct cText text;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cText_ctor( &text, "Any string", cool_normal_font , CLR_DKGRAY );
     cWinApp_clear_screen();
     // Puts the 'text' object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &text, 10, 40 );
     cWinApp_clear_screen();
     // Redraws the text
     cText_update(&text);
     ...
     cText_dtor( &text, LEAVE_MEMORY );


cXByte Struct Reference

Inheritance diagram for cXByte

Collaboration diagram for cXByte:

Public Methods
struct cXByte* | cXByte_ctor (struct cXByte *ptr_cxbyte, int w, char *title, char *num, int sln, int swd, char min_val, char max_val, struct Bitmap **ll, char *lsel)
void | cXByte_dtor (struct cXByte *ptr_cxbyte, int memory_flag)
void | cXByte_OK (struct cXByte *ptr_cxbyte)
void | cXByte_Esc (struct cXByte *ptr_cxbyte)
void | cXByte_Disconnect (struct cXByte *ptr_cxbyte)
bool | cXByte_Select (struct cXByte *ptr_cxbyte)
void | cXByte_update (struct cXByte *ptr_cxbyte)
struct cClip* | cXByte_GetParent (struct cXByte *ptr_cxbyte)
void | cXByte_Hide (struct cXByte *ptr_cxbyte)
void | cXByte_Show (struct cXByte *ptr_cxbyte)
void | cXByte_Disable (struct cXByte *ptr_cxbyte)
void | cXByte_Enable (struct cXByte *ptr_cxbyte)
char* | cXByte_GetTitle (struct cXByte *ptr_cxbyte)
bool | cXByte_proc (struct cXByte *ptr_cxbyte, struct Message *ptr_message)
void | cXByte_SelLeft (struct cXByte *ptr_cxbyte)
void | cXByte_SelRight (struct cXByte *ptr_cxbyte)
void | cXByte_SetLeft (struct cXByte *ptr_cxbyte, int index)
void | cXByte_SetRight (struct cXByte *ptr_cxbyte, int index)
void | cXByte_ScrollLR (struct cXByte *ptr_cxbyte)
void | cXByte_SetStart (struct cXByte *ptr_cxbyte)
void | cXByte_SaveStr (struct cXByte *ptr_cxbyte)

Detailed Description

A cXByte object is a a framed string with an icon on the left. It is used in main application screens. For more information, see the cXStr structure definition. You must call the cXByte_ctor function before use and the cXByte_dtor function after use.

See also:
Controls

Member Function Documentation

void cXByte_Disable ( struct cXByte * ptr_cxbyte )

Disables the cXByte object so that it cannot be selected.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None
See also:
cXByte_Enable.

void cXByte_Disconnect ( struct cXByte * ptr_cxbyte )

Disconnects a cXByte from its parent object.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None

void cXByte_Enable ( struct cXByte * ptr_cxbyte )

Enables a cXByte object so that it may be selected.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None
See also:
cXByte_Disable.

void cXByte_Esc ( struct cXByte * ptr_cxbyte )

Restores information.

Parameters:
ptr_cxbyte A pointer to the initialized cXByte object
Returns:
None
   #include <cywin.h>
     ...
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   picture_index = 2;
     struct cXByte* ptr_menu_item;
     char   value;
     ...
     init_module(&main_module);
     // Bitmap sequence contains three icons: picture of '<apples>', picture of 'potatoes', picture of '<oranges>', etc.
     BitmapSequence_ctor_Ex( &sq, "food_pictures.pic" );
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = BitmapSequence_get_bitmap(&sq, 3);
     bmps[4] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cXByte* )malloc ( sizeof ( struct cXByte ) );
     strcpy( buffer, "Initial value" );
     ...
     value = 20;
     // Item will be shown as follows: '<apples>' | "has discounted (in percent)" | ""
     cXByte_ctor( ptr_menu_item,
                  160,
                  "Percent is",
                  &value,
                  3,
                  80,
                  0,
                  100,
                  bmps,
                  &picture_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     // We have made changes then restored the previous state.
     cXByte_Esc(  ptr_menu_item  );
     ...
     cXByte_dtor( ptr_menu_item, FREE_MEMORY );
See also:
cXByte_OK.

struct cClip * cXByte_GetParent ( struct cXByte * ptr_cxbyte )

Returns a pointer to the parent object.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
A pointer to the parent object

char * cXByte_GetTitle ( struct cXByte * ptr_cxbyte )

Returns the item's title.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
The item's title

void cXByte_Hide ( struct cXByte * ptr_cxbyte )

Hides a cXByte object.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None
See also:
cXByte_Show.

void cXByte_OK ( struct cXByte * ptr_cxbyte )

Saves input information.
Also converts the string on the right side to an integer, if it has been changed.

Parameters:
ptr_cxbyte A pointer to the initialized cXByte object
Returns:
None
   #include <cywin.h>
     ...
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   picture_index = 2;
     struct cXByte* ptr_menu_item;
     char   value;
     ...
     init_module(&main_module);
     // Bitmap sequence contains three icons: picture of '<apples>', picture of 'potatoes', picture of '<oranges>', etc.
     BitmapSequence_ctor_Ex( &sq, "food_pictures.pic" );
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = BitmapSequence_get_bitmap(&sq, 3);
     bmps[4] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cXByte* )malloc ( sizeof ( struct cXByte ) );
     strcpy( buffer, "Initial value" );
     ...
     value = 20;
     // Item will be shown as follows: '<apples>' | "has discounted (in percent)" | ""
     cXByte_ctor( ptr_menu_item,
                  160,
                  "Percent is",
                  &value,
                  3,
                  80,
                  0,
                  100,
                  bmps,
                  &picture_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     // Saves the current state
     cXByte_OK(  ptr_menu_item  );
     ...
     cXByte_dtor( ptr_menu_item, FREE_MEMORY );
See also:
cXByte_Esc.

void cXByte_SaveStr ( struct cXByte * ptr_cxbyte )

Saves a Str to an external string.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None

void cXByte_ScrollLR ( struct cXByte * ptr_cxbyte )

Recalculates a StrBox.
Should be called if you moved the cursor or made changes to the string on the right side while it was selected.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None

void cXByte_SelLeft ( struct cXByte * ptr_cxbyte )

Selects the section on the item's left side (only if the item has the focus).

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None
See also:
cXByte_SelRight.

void cXByte_SelRight ( struct cXByte * ptr_cxbyte )

Selects the section on the item's right side (only if the item has the focus).

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None
See also:
cXByte_SelLeft.

bool cXByte_Select ( struct cXByte * ptr_cxbyte )

Selects a cXByte object.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
TRUE if the object was selected

void cXByte_SetLeft ( | struct cXByte * ptr_cxbyte,
 | int index )

Changes the left side's value by 'index'.

Parameters:
ptr_cxbyte | A pointer to a cXByte object
index | A new left side's value
Returns:
None
See also:
cXByte_SetRight.

void cXByte_SetRight ( | struct cXByte * ptr_cxbyte,
 | int index )

Changes the right side's value by 'index'.

Parameters:
ptr_cxbyte | A pointer to a cXByte object
index | A new right side's value
Returns:
None
See also:
cXByte_SetLeft.

void cXByte_SetStart ( struct cXByte * ptr_cxbyte )

Highlightes the entire string on the item's right side and positions the cursor at its end (only when the section on the item's right side is selected).

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None

void cXByte_Show ( struct cXByte * ptr_cxbyte )

Shows a cXByte object.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None
See also:
cXByte_Hide.

struct cXByte * cXByte_ctor ( | struct cXByte * ptr_cxbyte,
 | int w,
 | char * title,
 | char * num,
 | int sln,
 | int swd,
 | char min_val,
 | char max_val,
 | struct Bitmap ** ll,
 | char * lsel )

Constructor.
Creates an empty cXByte object.

Parameters:
ptr_cxbyte | A pointer to a cSItem struct
w | Item width in pixels (including left and right sections)
title | Title string
num | An integer value that will be converted into a string for the initial string in the item's right section
sln | Maximum character length of the right string on the item's right side (not including finishing '\0' )
swd | Maximum width, in pixels, of the visible part of the string on the item's right side (not including 2 pixels for the surrounding frame)
min_val | The lowest acceptable integer
max_val | The highest acceptable integer
ll | The bitmap list for the section on the item's left side - an array of pointers to bitmaps, with last pointer equaling 0
lsel | A reference to a variable that can be used to access the current left-side index
Returns:
A pointer to the initialized cXByte object
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   picture_index = 2;
     struct cXByte* ptr_menu_item;
     char   value;
     ...
     init_module(&main_module);
     // Bitmap sequence contains three icons: picture of '<apples>', picture of 'potatoes', picture of '<oranges>', etc.
     BitmapSequence_ctor_Ex( &sq, "food_pictures.pic" );
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = BitmapSequence_get_bitmap(&sq, 3);
     bmps[4] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cXByte* )malloc ( sizeof ( struct cXByte ) );
     strcpy( buffer, "Initial value" );
     ...
     value = 20;
     // Item will be shown as follows: '<apples>' | "has discounted (in percent)" | ""
     cXByte_ctor( ptr_menu_item,
                  160,
                  "Percent is",
                  &value,
                  3,
                  80,
                  0,
                  100,
                  bmps,
                  &picture_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     cXByte_dtor( ptr_menu_item, FREE_MEMORY );
   }

void cXByte_dtor ( | struct cXByte * ptr_cxbyte,
 | int memory_flag )

Destructor.
Deletes the cXByte object.

Parameters:
ptr_cxbyte | A pointer to the initialized cXByte object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   picture_index = 2;
     struct cXByte* ptr_menu_item;
     char   value;
     ...
     init_module(&main_module);
     // Bitmap sequence contains three icons: picture of '<apples>', picture of 'potatoes', picture of '<oranges>', etc.
     BitmapSequence_ctor_Ex( &sq, "food_pictures.pic" );
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = BitmapSequence_get_bitmap(&sq, 3);
     bmps[4] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cXByte* )malloc ( sizeof ( struct cXByte ) );
     strcpy( buffer, "Initial value" );
     ...
     value = 20;
     // Item will be shown as follows: '<apples>' | "has discounted (in percent)" | ""
     cXByte_ctor( ptr_menu_item,
                  160,
                  "Percent is",
                  &value,
                  3,
                  80,
                  0,
                  100,
                  bmps,
                  &picture_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     cXByte_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cXByte_proc ( | struct cXByte * ptr_cxbyte,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cxbyte | A pointer to a cXByte object
ptr_message | A pointer to the Message
Returns:
TRUE if the message was processed

void cXByte_update ( struct cXByte * ptr_cxbyte )

Updates a cXByte object.

Parameters:
ptr_cxbyte A pointer to a cXByte object
Returns:
None


cXItem Struct Reference

Inheritance diagram for cXItem

Collaboration diagram for cXItem:

Public Methods
struct cXItem* | cXItem_ctor (struct cXItem *ptr_cxitem, int width, char *title, char **rstr, char *rref, bool submenu, bool readonly, struct Bitmap **lbmp, char *lref)
void | cXItem_dtor (struct cXItem *ptr_cxitem, int memory_flag)
void | cXItem_SelLeft (struct cXItem *ptr_cxitem)
void | cXItem_SelRight (struct cXItem *ptr_cxitem)
void | cXItem_SetLeft (struct cXItem *ptr_cxitem, int index)
void | cXItem_SetRight (struct cXItem *ptr_cxitem, int index)
void | cXItem_OK (struct cXItem *ptr_cxitem)
void | cXItem_Esc (struct cXItem *ptr_cxitem)
bool | cXItem_proc (struct cXItem *ptr_cxitem, struct Message *ptr_message)
void | cXItem_Disconnect (struct cXItem *ptr_cxitem)
bool | cXItem_Select (struct cXItem *ptr_cxitem)
void | cXItem_update (struct cXItem *ptr_cxitem)
struct cClip* | cXItem_GetParent (struct cXItem *ptr_cxitem)
void | cXItem_Hide (struct cXItem *ptr_cxitem)
void | cXItem_Show (struct cXItem *ptr_cxitem)
void | cXItem_Disable (struct cXItem *ptr_cxitem)
void | cXItem_Enable (struct cXItem *ptr_cxitem)
char* | cXItem_GetTitle (struct cXItem *ptr_cxitem)

Detailed Description

The same type of string as in the cItem structure. However, it is possible to insert text on the right or an icon on the left, and to select one of the values assigned previously.

You must call the cXItem_ctor function before use and the cXItem_dtor function after use.

See also:
Controls

Member Function Documentation

void cXItem_Disable ( struct cXItem * ptr_cxitem )

Disables a cXItem object so that it cannot be selected.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
None
See also:
cXItem_Enable.

void cXItem_Disconnect ( struct cXItem * ptr_cxitem )

Disconnects a cXItem from its parent object.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
None

void cXItem_Enable ( struct cXItem * ptr_cxitem )

Enables a cXItem object so that it may be selected.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
None
See also:
cXItem_Disable.

void cXItem_Esc ( struct cXItem * ptr_cxitem )

Deselects the left or right section of the item (if either was selected), and restores L/Rsel from L/Rprev.

Parameters:
ptr_cxitem A pointer to the initialized cXItem object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char  left_index = 1;
       struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     // For example, icon "1" is selected now, you can bypass the icon "2" value and set the icon "3" value.
     cXItem_SetLeft( ptr_menu_item, 2 );
     ...
     // Restores the previous state.
     cXItem_Esc( ptr_menu_item, FREE_MEMORY );
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXItem_OK.

struct cClip * cXItem_GetParent ( struct cXItem * ptr_cxitem )

Returns a pointer to the cClip of the parent object.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
A pointer to the cClip of the parent object

char * cXItem_GetTitle ( struct cXItem * ptr_cxitem )

Returns the item's title.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
The item's title

void cXItem_Hide ( struct cXItem * ptr_cxitem )

Hides a cXItem object.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
None
See also:
cXItem_Show.

void cXItem_OK ( struct cXItem * ptr_cxitem )

Deselects the left or right section of the item (if either was selected), and saves L/Rsel to L/Rprev.

Parameters:
ptr_cxitem A pointer to the initialized cXItem object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
    // For example, icon "1" is selected now, you can bypass the icon "2" value and set the icon "3" value.
     cXItem_SetLeft( ptr_menu_item, 2 );
     ...
     // Save the current state.
     cXItem_OK( ptr_menu_item, FREE_MEMORY );
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXItem_Esc.

void cXItem_SelLeft ( struct cXItem * ptr_cxitem )

Selects the left-side section of the item (only if the item has focus).

Parameters:
ptr_cxitem A pointer to the initialized cXItem object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     // If you on the right item part now you can select the left item part. Note, the focus would be on the left part.
     cXItem_SelLeft( ptr_menu_item );
     ...
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXItem_SelRight.

void cXItem_SelRight ( struct cXItem * ptr_cxitem )

Selects the right-side section of the item (only if the item has focus).

Parameters:
ptr_cxitem A pointer to the initialized cXItem object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     // If you on the left item part now you can select the right item part. Note, the focus would be on the right part.
     cXItem_SelRight( ptr_menu_item );
     ...
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXItem_SelLeft.

bool cXItem_Select ( struct cXItem * ptr_cxitem )

Selects cXItem object.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
TRUE if the object was selected

void cXItem_SetLeft ( | struct cXItem * ptr_cxitem,
 | int index )

Changes the left section's value by 'index'.

Parameters:
ptr_cxitem | A pointer to the initialized cXItem object
index | A new left section's value
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     // For example, "Digit 1" value is selected now, you can bypass "Digit 2" value and set the "Digit 3" value.
     cXItem_SetRight( ptr_menu_item, 2 );
     ...
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXItem_SetRight.

void cXItem_SetRight ( | struct cXItem * ptr_cxitem,
 | int index )

Changes the right section's value by 'index'.

Parameters:
ptr_cxitem | A pointer to the initialized cXItem object
index | A new right section's value
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     // For example, icon "1" is selected now, you can bypass the icon "2" value and set the icon "3" value.
     cXItem_SetLeft( ptr_menu_item, 2 );
     ...
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXItem_SetLeft.

void cXItem_Show ( struct cXItem * ptr_cxitem )

Shows a cXItem object.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
None
See also:
cXItem_Hide.

struct cXItem * cXItem_ctor ( | struct cXItem * ptr_cxitem,
 | int width,
 | char * title,
 | char ** rstr,
 | char * rref,
 | bool submenu,
 | bool readonly,
 | struct Bitmap ** lbmp,
 | char * lref )

Constructor.
Creates a cXItem object.

Parameters:
ptr_cxitem | A pointer to cXItem structure
width | Item's width in pixels
title | Item's title.
rstr | The string in the right-side section - an array of pointers to strings, with the last pointer equaling 0
rref | A pointer to a variable that can be used to access the current right-side index
submenu | Determines if there is a submenu
readonly | Forbids entering and changing the section on the item's right side.
lbmp | The bitmap list for the left-side section - an array of pointers to bitmaps, with last pointer equaling 0
lref | A reference to a variable that can be used to access the current left-side index. Initial value is an index of an initially displayed bitmap
Returns:
A pointer to the initialized cXItem object
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }

void cXItem_dtor ( | struct cXItem * ptr_cxitem,
 | int memory_flag )

Destructor.
It deletes the cXItem object.

Parameters:
ptr_cxitem | A pointer to the initialized cXItem object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cXItem_proc ( | struct cXItem * ptr_cxitem,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cxitem | A pointer to the initialized cXItem object
ptr_message | A pointer to a Message
Returns:
TRUE if the message was processed
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   right_index = 1;
     char   left_index = 1;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[4] = {
                                             "Digit 1",
                                             "Digit 2",
                                             "Digit 3",
                                             '\0'
                                          };
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     // Item will be shown as follows: '2' | "Now digit is" | "Digit 2"
     cXItem_ctor( ptr_menu_item,
                  160,
                  "Now digit is",
                  sz_menu_text,
                  &right_index,
                  FALSE,
                  FALSE,
                  bmps,
                  &left_index );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     // cXItem will be redraw automatically now.
     cXItem_proc( ptr_menu_item, ptr_message );
     ...
     // Now you can use the <Select> button to change values on the left part of the item: "Digit 1"->"Digit 2"-> etc.
     // To move to the right part use the arrows buttons.
     // Now you can use the <Select> button to change values on the right part of the item: icon '1'->icon '2'-> etc.
     ...
     // For example, icon "1" is selected now, you can bypass the icon "2" value and set the icon "3" value.
     cXItem_SetLeft( ptr_menu_item, 2 );
     ...
     // Restore the previous state.
     cXItem_Esc( ptr_menu_item, FREE_MEMORY );
     cXItem_dtor( ptr_menu_item, FREE_MEMORY );
   }

void cXItem_update ( struct cXItem * ptr_cxitem )

Updates a cXItem object.

Parameters:
ptr_cxitem A pointer to a cXItem object
Returns:
None


cXStr Struct Reference

Inheritance diagram for cXStr

Collaboration diagram for cXStr:

Public Methods
struct cXStr* | cXStr_ctor (struct cXStr *ptr_cxstr, int w, char *title, char *st, int sln, int swd, struct Bitmap **lbmp, char *lsel, bool readonly)
void | cXStr_dtor (struct cXStr *ptr_cxstr, int memory_flag)
void | cXStr_SetStart (struct cXStr *ptr_cxstr)
void | cXStr_SelRight (struct cXStr *ptr_cxstr)
void | cXStr_OK (struct cXStr *ptr_cxstr)
void | cXStr_Esc (struct cXStr *ptr_cxstr)
void | cXStr_SaveStr (struct cXStr *ptr_cxstr)
bool | cXStr_proc (struct cXStr *ptr_cxstr, struct Message *ptr_message)
void | cXStr_Disconnect (struct cXStr *ptr_cxstr)
bool | cXStr_Select (struct cXStr *ptr_cxstr)
void | cXStr_update (struct cXStr *ptr_cxstr)
struct cClip* | cXStr_GetParent (struct cXStr *ptr_cxstr)
void | cXStr_Hide (struct cXStr *ptr_cxstr)
void | cXStr_Show (struct cXStr *ptr_cxstr)
void | cXStr_Disable (struct cXStr *ptr_cxstr)
void | cXStr_Enable (struct cXStr *ptr_cxstr)
char* | cXStr_GetTitle (struct cXStr *ptr_cxstr)
void | cXStr_SelLeft (struct cXStr *ptr_cxstr)
void | cXStr_SetLeft (struct cXStr *ptr_cxstr, int index)
void | cXStr_SetRight (struct cXStr *ptr_cxstr, int index)

Detailed Description

A cXStr object might have an icon on the left and/or additional text on the right. It is possible to input text into the right field. You must call the cXStr_ctor function before use and the cXStr_dtor function after use.

See also:
Controls

Member Function Documentation

void cXStr_Disable ( struct cXStr * ptr_cxstr )

Disables a cXStr object so that it cannot be selected.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
None
See also:
cXStr_Enable.

void cXStr_Disconnect ( struct cXStr * ptr_cxstr )

Disconnects a cXStr from its parent object.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
None

void cXStr_Enable ( struct cXStr * ptr_cxstr )

Enables a cXStr object so that it may be selected.

Parameters:
ptr_cxstr A pointer to a cXStr object.
Returns:
None
See also:
cXStr_Disable.

void cXStr_Esc ( struct cXStr * ptr_cxstr )

Clears an edited string and deselects the section on the item's right side(if it was selected).
Behavior for the left side is not changed.

Parameters:
ptr_cxstr A pointer to the initialized cXStr object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     ...
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     // We have made changes then restore the previous state.
     cXStr_Esc(  ptr_menu_item  );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXStr_OK.

struct cClip * cXStr_GetParent ( struct cXStr * ptr_cxstr )

Returns a pointer to the cClip of the parent object.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
A pointer to the cClip of the parent object

char * cXStr_GetTitle ( struct cXStr * ptr_cxstr )

Returns the item's title.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
The item's title

void cXStr_Hide ( struct cXStr * ptr_cxstr )

Hides a cXStr object.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
None
See also:
cXStr_Show.

void cXStr_OK ( struct cXStr * ptr_cxstr )

Saves an edited string and deselects the section on the item's right side (if it was selected).
Behavior for the left side is not changed.

Parameters:
ptr_cxstr A pointer to the initialized cXStr object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     // Saves the current state
     cXStr_OK(  ptr_menu_item  );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXStr_Esc.

void cXStr_SaveStr ( struct cXStr * ptr_cxstr )

Saves a Str to an external string.

Parameters:
ptr_cxstr A pointer to the initialized cXStr object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     ...
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     // If we made a change in the right section of the item, this function saves it in the 'buffer'.
     cXStr_SaveStr(  ptr_menu_item  );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }

void cXStr_SelLeft ( struct cXStr * ptr_cxstr )

Selects the section on the item's left side (only if the item has the focus).

Parameters:
ptr_cxstr A pointer to the initialized cXStr object
Returns:
None
See also:
cXStr_SelRight.

void cXStr_SelRight ( struct cXStr * ptr_cxstr )

Selects the section on the item's right side (only if the item has the focus).

Parameters:
ptr_cxstr A pointer to the initialized cXStr object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     ...
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     // Selects the right part.
     cXStr_SelRight(  ptr_menu_item  );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
cXStr_SelLeft.

bool cXStr_Select ( struct cXStr * ptr_cxstr )

Selects a cXStr object.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
TRUE if the object was selected

void cXStr_SetLeft ( | struct cXStr * ptr_cxstr,
 | int index )

Changes the left section's value by 'index'.

Parameters:
ptr_cxstr | A pointer to a cXStr object
index | A new left section's value
Returns:
None
See also:
cXStr_SetRight.

void cXStr_SetRight ( | struct cXStr * ptr_cxstr,
 | int index )

Changes right section's value by 'index'.

Parameters:
ptr_cxstr | A pointer to a cXStr object.
index | A new right section's value
Returns:
None
See also:
cXStr_SetLeft.

void cXStr_SetStart ( struct cXStr * ptr_cxstr )

Highlightes the entire whole right-side string, and positions the cursor at its end (only when the section on the item's right side is selected).

Parameters:
ptr_cxstr A pointer to the initialized cXStr object
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     ...
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     ...
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     // Highlights the right part.
     cXStr_SetStart(  ptr_menu_item  );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }

void cXStr_Show ( struct cXStr * ptr_cxstr )

Shows a cXStr object.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
None
See also:
cXStr_Hide.

struct cXStr * cXStr_ctor ( | struct cXStr * ptr_cxstr,
 | int w,
 | char * title,
 | char * st,
 | int sln,
 | int swd,
 | struct Bitmap ** lbmp,
 | char * lsel,
 | bool readonly )

Constructor.
Creates a cXStr object.

Parameters:
ptr_cxstr | A pointer to the cXStr structure
w | An item's width in pixels (including left and right sections)
title | A title string
st | The initial value for the string on the item's right side
sln | Maximum character length of the string on the item's right side (not including '\0')
swd | Maximum width, in pixels, of the viewable portion of the string on the item's right side (not including 2 pixels for surrounding the frame)
lbmp | The bitmap lost for the section on the item's left side - an array of pointers to bitmaps, with last pointer equaling 0
lsel | A reference to a variable that can be used to access the current left-side index
readonly | Forbids entering and changing the section on the item's right side
Returns:
A pointer to the initialized cXStr object
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }

void cXStr_dtor ( | struct cXStr * ptr_cxstr,
 | int memory_flag )

Destructor.
Deletes the cXStr object.

Parameters:
ptr_cxstr | A pointer to the initialized cXStr object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     ...
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool cXStr_proc ( | struct cXStr * ptr_cxstr,
 | struct Message * ptr_message )

The Message-processing function.

Parameters:
ptr_cxstr | A pointer to the initialized cXStr object
ptr_message | A pointer to a Message
Returns:
TRUE if the message was processed
   #include <cywin.h>
     ...
   {
     struct BitmapSequence sq;
     struct Bitmap* bmps[4];
     char   icon_index = 2;
     struct cItem* ptr_menu_item;
     char   buffer[100];
     struct Message* ptr_message;
     ...
     init_module(&main_module);
     // Bitmap sequence contains three icons: digit '1', digit '2', digit '3'.
     BitmapSequence_ctor_Ex(&sq, "digits.pic");
     bmps[0] = BitmapSequence_get_bitmap(&sq, 0);
     bmps[1] = BitmapSequence_get_bitmap(&sq, 1);
     bmps[2] = BitmapSequence_get_bitmap(&sq, 2);
     bmps[3] = NULL;
     cWinApp_clear_screen();
     ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
     strcpy( buffer, "Initial value" );
     ...
     // Item will be shown as follows: '3' | "Any item" | "Initial value"
     cXStr_ctor( ptr_menu_item,
                  160,
                  "Any item",
                  buffer,
                  30,
                  80,
                  bmps,
                  &icon_index,
                  FALSE );
     cWinApp_AddObj( main_module.m_process, ptr_menu_item, 0, 40 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     // Processes the messages that the cXStr control manages.
     cXStr_proc( ptr_menu_item, ptr_message );
     ...
     // If we made change in the right item part this function saves it in the 'buffer'.
     cXStr_SaveStr(  ptr_menu_item  );
     ...
     cXStr_dtor( ptr_menu_item, FREE_MEMORY );
   }

void cXStr_update ( struct cXStr * ptr_cxstr )

Updates a cXStr object.

Parameters:
ptr_cxstr A pointer to a cXStr object
Returns:
None


Built-in String Constants

Variables
char* | str_Your
char* | str_Partner
char* | str_Illegal
char* | str_move
char* | str_again
char* | str_wait
char* | str_please
char* | str_Link_off
char* | str_Link_off_again
char* | str_Really_exit
char* | str_Partner_surrender
char* | str_Waiting_link
char* | str_Draw
char* | str_Draw_suggestion
char* | str_Draw_waiting
char* | str_Draw_rejected
char* | str_You_win
char* | str_You_lose
char* | str_1st_win
char* | str_2nd_win
char* | str_Tie_up
char* | str_Enter_file_name
char* | str_Waiting_SyPage
char* | str_no_CyPage
char* | str_Save_Changes
char* | str_Score_Again
char* | str_Declined_To_Play
char* | str_Declined_To_Play_Game

Detailed Description

String constants that are instantly usable from within your application or game.

Variable Documentation

char * str_1st_win

String "First player WINS!".

char * str_2nd_win

String "Second player WINS!".

char * str_Declined_To_Play

String "%s declined to play with you".

char * str_Declined_To_Play_Game

String "%s declined to play %s".

char * str_Draw

String "Draw.".

char * str_Draw_rejected

String "Draw rejected!".

char * str_Draw_suggestion

String "Your partner suggests a draw, do you agree?".

char * str_Draw_waiting

String "Waiting for answer...".

char * str_Enter_file_name

String "Enter file name".

char * str_Illegal

String "Illegal".

char * str_Link_off

String "Link OFF.".

char * str_Link_off_again

String "Link off.\nRestore connection?".

char * str_Partner

String "Partner's".

char * str_Partner_surrender

String "Your partner surrendered.\nYou WIN!".

char * str_Really_exit

String "Do you really want to quit?".

char * str_Save_Changes

String "Do you wish to save changes?".

char * str_Score_Again

String "Your final score: %d.\nDo you want to start again?".

char * str_Tie_up

String "Tie.".

char * str_Waiting_SyPage

String "Waiting CyPage...".

char * str_Waiting_link

String "Waiting for link...".

char * str_You_lose

String "You lose.".

char * str_You_win

String "You WIN!".

char * str_Your

String " Your".

char * str_again

String " again".

char * str_move

String " move".

char * str_no_CyPage

String "no CyPage".

char * str_please

String " please...".

char * str_wait

String " Wait,".


File I/O

Defines
#define | MAX_NAME_LEN 64
#define | FS_NONE 0
#define | FS_CREATED 1
#define | FS_REMOVED 2
#define | FC_CHANGED 3
#define | FC_RENAMED 4
#define | FC_FORMATTED 5
#define | SEEK_SET 0
#define | SEEK_CUR 1
#define | SEEK_END 2

Typedefs
typedef int | seek_t

Enumerations
enum Flags {
FLAG_BAD = 1,
FLAG_EOF = 2,
FLAG_EXCEPTIONS = 4
}

Functions
struct Input* | open_resource (int index)
struct Input* | open_resource_Ex (char *sz_file_name)
int | mFileName_max_file_name_length (void)
bool | mFileName_is_valid_file_name (char *sz_full_name)
void | mFileName_split_path (char *sz_full_name, char *sz_device_name, char *sz_file_name)
void | mFileName_make_path (char *sz_full_name, char *sz_device_name, char *sz_file_name)
void | mFileName_get_path (char *sz_full_name, char *sz_path)
char* | mFileName_current_device_name (void)

Variables
char | MP3_DRIVE_NAME []
char | DEFAULT_DRIVE_NAME []
char | DRIVE_A_NAME []
char | DRIVE_B_NAME []

Compounds
struct | Archive | Archive storage. A file that holds more files inside, each one of may be compressed
struct | File | The object to be manipulated
struct | FileFind | File finder. Implements the functions needed to find a set of files
struct | FileInput | The Input file stream
struct | FileOutput | The Output file stream
struct | Input | An abstract object for sequential data access objects
struct | Output | An abstract object for the sequential data access objects

Detailed Description

Structures of the File I/O section define the most basic file operations in the CyOS. These rules apply to file names that include any of these valid symbols:
valid_symbols = "qwertyuiopasdfghjklzxcvbnmQWERTYUIOPASDFGHJKLZXCVBNM 1234567890-_+.()";
start_disabled = " -+.";
end_disabled = " -+.";

Define Documentation

#define FC_CHANGED 3

File was changed.

#define FC_FORMATTED 5

Disk was formatted.

#define FC_RENAMED 4

File was renamed.

#define FS_CREATED 1

File was created.

#define FS_NONE 0

State is undefined.

#define FS_REMOVED 2

File was removed.

#define MAX_NAME_LEN 64

Maximum filename length.

#define SEEK_CUR 1

Seek from the current position (a positive offset indicates towards end of file).

#define SEEK_END 2

Seek from the end.
A negative offset indicates closer to the beginning of the file; zero offset means set after the last byte of the file.

#define SEEK_SET 0

Seek to the absolute position.

Typedef Documentation

typedef int seek_t

Defines the initial position in the stream and must be one of the following: SEEK_SET, SEEK_CUR or SEEK_END.

See also:
SEEK_SET, SEEK_CUR, SEEK_END.

Enumeration Type Documentation

enum Flags

Stream's state flags.
Stream state is represented by setting and clearing following flags:

Enumeration values:
FLAG_BAD | is set if the stream object is invalid.
FLAG_EOF | is set when the stream reaches the end of the file.
FLAG_EXCEPTIONS | indicates that implementation must throw exceptions on errors.

Function Documentation

char * mFileName_current_device_name ( void )

Retrieves the name of the current flash device.

Returns:
Name of the current flash device.
       #include <cybiko.h>
       ...
       int index;
       char* sz_tmp_full_name;
       char sz_tmp_name[16];
       int max_file_name = mFileName_max_file_name_length();
       ...
       //  Generates name for the temporary file;
       sz_tmp_full_name = (char*) malloc( max_file_name );
       do
       {
         sprintf( sz_tmp_name, "%ld.tmp", time() );
         mFileName_make_path( sz_tmp_full_name,
                              mFileName_current_device_name(),
                              sz_tmp_name );
       }while( ! mFileName_is_valid_file_name( sz_tmp_full_name ) );
       ...
       free( sz_tmp_full_name );
       ...

void mFileName_get_path ( | char * sz_full_name,
 | char * sz_path )

Retrieves the path to the file from the absolute file name.

Parameters:
sz_full_name | absolute name of the file.
sz_path | buffer in which the file path will be stored.
Returns:
None.
       #include <cybiko.h>
       ...
       struct module_t main_module;
       char* sz_application_path;
       ...
       init_module( &main_module );
       ...
       //  Retrieves application name.
       sz_application_path = (char*) malloc( mFileName_max_file_name_length() );
       mFileName_get_path( Archive_archive_name( main_module.m_process->module->archive ),
                           sz_application_path );
       ...
       TRACE("Path to the application is %s", sz_application_path );
       ...
       free(sz_application_path);

bool mFileName_is_valid_file_name ( char * sz_full_name )

Verifies that the file name is valid.

Parameters:
sz_full_name absolute name of the file.
Returns:
TRUE if name of the file is valid.
       #include <cybiko.h>
       ...
       int index;
       char* sz_tmp_full_name;
       char sz_tmp_name[16];
       int max_file_name = mFileName_max_file_name_length();
       ...
       //  Generates name for the temporary file;
       sz_tmp_full_name = (char*) malloc( max_file_name );
       do
       {
         sprintf( sz_tmp_name, "%ld.tmp", time() );
         mFileName_make_path( sz_tmp_full_name,
                              mFileName_current_device_name(),
                              sz_tmp_name );
       }while( ! mFileName_is_valid_file_name( sz_tmp_full_name ) );
       ...
       free( sz_tmp_full_name );
       ...

void mFileName_make_path ( | char * sz_full_name,
 | char * sz_device_name,
 | char * sz_file_name )

Creates an absolute file name by combining the file name with the device name.

Parameters:
sz_full_name | buffer in which the absolute file name will be stored.
sz_device_name | device name.
sz_file_name | file name.
Returns:
None.
       #include <cybiko.h>
       ...
       int index;
       char* sz_tmp_full_name;
       char sz_tmp_name[16];
       int max_file_name = mFileName_max_file_name_length();
       ...
       //  Generates name for the temporary file;
       sz_tmp_full_name = (char*) malloc( max_file_name );
       do
       {
         sprintf( sz_tmp_name, "%ld.tmp", time() );
         mFileName_make_path( sz_tmp_full_name,
                              mFileName_current_device_name(),
                              sz_tmp_name );
       }while( ! mFileName_is_valid_file_name( sz_tmp_full_name ) );
       ...
       free( sz_tmp_full_name );
       ...

int mFileName_max_file_name_length ( void )

Retrieves the maximum file name length.

Returns:
Maximum length of the file name.
       #include <cybiko.h>
       ...
       int index;
       char* sz_tmp_full_name;
       char sz_tmp_name[16];
       int max_file_name = mFileName_max_file_name_length();
       ...
       //  Generates name for the temporary file;
       sz_tmp_full_name = (char*) malloc( max_file_name );
       do
       {
         sprintf( sz_tmp_name, "%ld.tmp", time() );
         mFileName_make_path( sz_tmp_full_name,
                              mFileName_current_device_name(),
                              sz_tmp_name );
       }while( ! mFileName_is_valid_file_name( sz_tmp_full_name ) );
       ...
       free( sz_tmp_full_name );
       ...

void mFileName_split_path ( | char * sz_full_name,
 | char * sz_device_name,
 | char * sz_file_name )

Splits the absolute file name into device name and file name.

Parameters:
sz_full_name | absolute file name.
sz_device_name | buffer in which the device name will be stored.
sz_file_name | buffer in which the file name will be stored.
Returns:
None.
       #include <cybiko.h>
       ...
       struct module_t main_module;
       char* sz_application_name;
       ...
       init_module( &main_module );
       ...
       //  Retrieves application name.
       sz_application_name = (char*) malloc( mFileName_max_file_name_length() );
       mFileName_split_path( Archive_archive_name( main_module.m_process->module->archive ),
                             NULL,
                             sz_application_name );
       ...
       TRACE("Name of the application is %s", sz_application_name );
       ...
       free(sz_application_name);

struct Input * open_resource ( int index )

Returns the resource from the current archive, using resource index.

Returns:
Pointer to the initialized Input object.
       #include <cybiko.h>
       ...
       struct Input* ptr_input;
       struct Bitmap bmp;
       ...
       Bitmap_ctor(&bmp);
       ...
       //  Your make file must have the archive resource "bmp.pic" linked
       //  by the filer. "bmp.pic" must be the first in the resource
       //  list (index = 0). For example, see the Cybiko Compiler's
       //  Introduction Section
       ptr_input = open_resource( 0 );
       if( !Bitmap_load( &bmp, ptr_input ) )
           return FALSE;
       else
           ...
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
open_resource_Ex.

struct Input * open_resource_Ex ( char * sz_file_name )

Returns the resource from the current archive, using the resource name.

Returns:
Pointer to the initialized Input object.
       #include <cybiko.h>
       ...
       struct Input* ptr_input;
       struct Bitmap bmp;
       ...
       Bitmap_ctor(&bmp);
       ...
       //  Your make file must have the archive resource "bmp.pic" linked
       //  by filer. For example, see the Cybiko Compiler's
       //  Introduction Section
       ptr_input = open_resource_Ex( "bmp.pic" );
       if( !Bitmap_load( &bmp, ptr_input ) )
           return FALSE;
       else
           ...
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
open_resource.

Variable Documentation

char DEFAULT_DRIVE_NAME[]

Name of the default flash device.

       #include <cybiko.h>
       ...
       TRACE( "Names of the devices:" );
       TRACE( "\tMp3 player: %s", MP3_DRIVE_NAME );
       TRACE( "\tDrive A: %s", DRIVE_A_NAME );
       TRACE( "\tDrive B: %s", DRIVE_B_NAME );
       TRACE( "\tDefault Drive: %s", DEFAULT_DRIVE_NAME );
       ...

char DRIVE_A_NAME[]

Name of flash device A.

       #include <cybiko.h>
       ...
       TRACE( "Names of the devices:" );
       TRACE( "\tMp3 player: %s", MP3_DRIVE_NAME );
       TRACE( "\tDrive A: %s", DRIVE_A_NAME );
       TRACE( "\tDrive B: %s", DRIVE_B_NAME );
       TRACE( "\tDefault Drive: %s", DEFAULT_DRIVE_NAME );
       ...

char DRIVE_B_NAME[]

Name of flash device B.

       #include <cybiko.h>
       ...
       TRACE( "Names of the devices:" );
       TRACE( "\tMp3 player: %s", MP3_DRIVE_NAME );
       TRACE( "\tDrive A: %s", DRIVE_A_NAME );
       TRACE( "\tDrive B: %s", DRIVE_B_NAME );
       TRACE( "\tDefault Drive: %s", DEFAULT_DRIVE_NAME );
       ...

char MP3_DRIVE_NAME[]

Name of MP3 player device.

       #include <cybiko.h>
       ...
       TRACE( "Names of the devices:" );
       TRACE( "\tMp3 player: %s", MP3_DRIVE_NAME );
       TRACE( "\tDrive A: %s", DRIVE_A_NAME );
       TRACE( "\tDrive B: %s", DRIVE_B_NAME );
       TRACE( "\tDefault Drive: %s", DEFAULT_DRIVE_NAME );
       ...


Archive Struct Reference

Public Methods
void | Archive_ctor (struct Archive *ptr_archive, char *sz_archive_name)
void | Archive_dtor (struct Archive *ptr_archive, int memory_flag)
bool | Archive_is_good (struct Archive *ptr_archive)
struct Input* | Archive_open (struct Archive *ptr_archive, int entry)
struct Input* | Archive_open_Ex (struct Archive *ptr_archive, char *sz_name)
struct Output* | Archive_open_write (struct Archive *ptr_archive, int entry)
struct Output* | Archive_open_write_Ex (struct Archive *ptr_archive, char *sz_name)
int | Archive_count_entries (struct Archive *ptr_archive)
char* | Archive_get_name (struct Archive *ptr_archive, int entry)
char* | Archive_archive_name (struct Archive *ptr_archive)

Detailed Description

An archive is a file that holds more files inside it, with possible compression of every one of them. Right now only one compression method is supported, but space for 254 more is reserved. You get standard Input* when opening a file from inside the archive, and you should handle it like regular input. If files are not compressed, random access methods can be used for their Input objects.

Currently, compressed streams do not support random access. Using archives is the preferred way to handle large groups of files. Getting files from an archive might be faster than opening a file, especially if there are a lot of them.

You must call the Archive_ctor() function before retrieving a file from an archive and Archive_dtor() afterward. The pointer to the archive of the current application can be obtained in the following manner:

      #include <cybiko.h>
      ...
      struct module_t main_module;
      ...
      init_module( &main_module );
      //  main_module.m_process->module->archive is the pointer to the
      //  Archive of the current application.
      ...
See also:
File I/O

Member Function Documentation

char * Archive_archive_name ( struct Archive * ptr_archive )

Returns the archive name.

Parameters:
ptr_archive A pointer to an initialized Archive object
Returns:
Name of the archive
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }

int Archive_count_entries ( struct Archive * ptr_archive )

Returns the number of entries (resources) in the archive.

Parameters:
ptr_archive A pointer to an initialized Archive object
Returns:
The number of entries (resources) in the archive
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }

void Archive_ctor ( | struct Archive * ptr_archive,
 | char * sz_archive_name )

Initializes an Archive object for a specified archive file.

Parameters:
ptr_archive | A pointer to an initialized Archive object
sz_archive_name | The name of the archive file
Returns:
None
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_dtor

void Archive_dtor ( | struct Archive * ptr_archive,
 | int memory_flag )

Destructor of an Archive object.
It frees all used resources.

Parameters:
ptr_archive | A pointer to the Archive object to be destroyed
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If malloc() was used to allocate the object's memory, use FREE_MEMORY. If the object was static or allocated in stack, use LEAVE_MEMORY.
Returns:
None
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_ctor, FREE_MEMORY, LEAVE_MEMORY.

char * Archive_get_name ( | struct Archive * ptr_archive,
 | int entry )

Retrieves the name of the Nth entry.

Parameters:
ptr_archive | A pointer to the initialized Archive object.
entry | The element's index in the Archive
Returns:
Name of the entry with the specified index
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
      }

bool Archive_is_good ( struct Archive * ptr_archive )

Checks whether the Archive object is valid.

Parameters:
ptr_archive A pointer to the Archive object to be checked
Returns:
TRUE if the Archive object is valid
      #include <cybiko.h>
      ...
      {
        int index;
        int max_entries;
        struct Archive resources;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          TRACE( "Archive :%s Entries:", Archive_archive_name( &resources ) );
          max_entries = Archive_count_entries( &resources );
          for( index = 0; index < max_entries ; index ++ )
          {
            TRACE( "%d   %s", index + 1, Archive_get_name( &resources, index ) );
          }
          ...
        }
        ...
        Archive_dtor( &resources, LEAVE_MEMORY );
     }

struct Input * Archive_open ( | struct Archive * ptr_archive,
 | int entry )

Opens an Input for the specified resource index.
All files in the archive are numbered. These numbers are often referenced as resource IDs. Archive_open constructs the right kind of stream for an entry and returns it. Use it the same way as a regular stream. Important: don't forget to delete it when you're done with it

Parameters:
ptr_archive | A pointer to an initialized Archive object
entry | The entry number (resource id)
Returns:
Input object to read the specified file from the archive, or NULL if there is no such Id or not enough memory for the operation
      #include <cybiko.h>
      ...
      {
        struct BitmapSequence movie_frames;
        struct Archive resources;
        struct Input* ptr_input;
        ...
        Archive_ctor( &resources, "movie.dat" );
        if( Archive_is_good( &resources ) )
        {
          ptr_input = Archive_open( &resources, 0 );
          BitmapSequence_ctor( &movie_frames );
          BitmapSequence_load( &movie_frames, ptr_input );
          ...
        }
        ...
        BitmapSequence_dtor( &movie_frames, LEAVE_MEMORY );
        Input_dtor( ptr_input, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open_Ex.

struct Input * Archive_open_Ex ( | struct Archive * ptr_archive,
 | char * sz_name )

Opens an Input from the archive for the file named.
It works just like Archive_open() but looks for files by name.

Parameters:
ptr_archive | A pointer to an initialized Archive object
sz_name | The name of the file inside the archive
Returns:
A pointer to a corresponding Input object, or NULL if the file is not found or there is not enough memory to open it.
      #include <cybiko.h>
      ...
      {
        struct BitmapSequence movie_frames;
        struct Archive resources;
        struct Input* ptr_input;
        ...
        Archive_ctor( &resources, "movie.dat" );
        if( Archive_is_good( &resources ) )
        {
          ptr_input = Archive_open_Ex( &resources, "frames.pic" );
          BitmapSequence_ctor( &movie_frames );
          BitmapSequence_load( &movie_frames, ptr_input );
          ...
        }
        ...
        BitmapSequence_dtor( &movie_frames, LEAVE_MEMORY );
        Input_dtor( ptr_input, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open.

struct Output * Archive_open_write ( | struct Archive * ptr_archive,
 | int entry )

All files in the archive are numbered.
These numbers are often referenced as resource IDs. Archive_open_write constructs the right kind of stream for an entry, and returns it. Use it the same way as a regular stream. Important: don't forget to delete it when you're done with it! FILE MUST NOT BE COMPRESSED!

Parameters:
ptr_archive | A pointer to an initialized Archive object.
entry | The entry number (resource ID).
Returns:
Output object to write to the specified archive file; or NULL if there is no such ID, not enough memory for the operation, or the file is compressed
      #include <cybiko.h>
      ...
      {
        struct Archive resources;
        struct Output* ptr_output;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          ptr_output = Archive_open_write( &resources, 0);
          Output_write( ptr_output,
                        game_information,
                        sizeof( struct GameInformation ) );
          ...
        }
        ...
        Output_dtor( ptr_output, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open_write_Ex.

struct Output * Archive_open_write_Ex ( | struct Archive * ptr_archive,
 | char * sz_name )

Opens an Output for the archive file named.
It works just like Archive_open_write, but looks for files by name. Archive_open_write_Ex constructs the right kind of stream for an entry, and returns it. Use it the same way as a regular stream. Important: don't forget to delete it when you're done with it! FILE MUST NOT BE COMPRESSED!

Parameters:
ptr_archive | A pointer to an initialized Archive object.
sz_name | The name of the file inside the archive
Returns:
A pointer to a corresponding Output object; or NULL if the file is not found, there is not enough memory to open it, or the file is compressed.
      #include <cybiko.h>
      ...
      {
        struct Archive resources;
        struct Output* ptr_output;
        ...
        Archive_ctor( &resources, "renju.sav" );
        if( Archive_is_good( &resources ) )
        {
          ptr_output = Archive_open_write_Ex( &resources, "game_1" );
          Output_write( ptr_output,
                        game_information,
                        sizeof( struct GameInformation ) );
          ...
        }
        ...
        Output_dtor( ptr_output, FREE_MEMORY );
        Archive_dtor( &resources, LEAVE_MEMORY );
      }
See also:
Archive_open_write.


File Struct Reference

Public Methods
struct File* | File_ctor (struct File *ptr_file)
struct File* | File_ctor_Ex (struct File *ptr_file, char *sz_file_name)
bool | File_is_free (struct File *ptr_file)
time_t | File_get_date (struct File *ptr_file)
bool | File_set_date (struct File *ptr_file, time_t date)
bool | File_get_info (struct File *ptr_file, char *sz_file_name)
long | File_free_bytes_total (char *sz_device_name)
long | File_free_user_bytes_total (char *sz_device_name)
long | File_files_total (char *sz_device_name)
long | File_bytes_total (char *sz_device_name)
long | File_blocks_total (char *sz_device_name)
long | File_bad_blocks_total (char *sz_device_name)
int | File_block_size (char *sz_device_name)
long | File_free_blocks_total (char *sz_device_name)
bool | File_bootable (char *sz_device_name)
bool | File_is_valid_name (char *sz_file_name)
bool | File_rename (char *sz_old_filename, char *sz_new_filename)
bool | File_remove (char *sz_file_name)
bool | File_exists (char *sz_file_name)
void | File_dtor (struct File *ptr_file, int memory_flag)

Public Attributes
char | name [MAX_NAME_LEN]
long | size
time_t modification_time

Detailed Description

Object for manipulation files.

See also:
File I/O

Member Function Documentation

long File_bad_blocks_total ( char * sz_device_name )

Returns the total number of bad blocks on the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
The total number of bad blocks on the specified device
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...
See also:
File_blocks_total.

int File_block_size ( char * sz_device_name )

Returns the block size for the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
The block size for the specified device
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...

long File_blocks_total ( char * sz_device_name )

Returns the total number of blocks on the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
The total number of blocks on the specified device
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...
See also:
File_bad_blocks_total.

bool File_bootable ( char * sz_device_name )

Returns TRUE if the specified device is bootable.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
TRUE if the specified device is bootable
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...

long File_bytes_total ( char * sz_device_name )

Returns the total number of bytes on the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
The total number of bytes on the specified device
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...
See also:
File_files_total.

struct File * File_ctor ( struct File * ptr_file )

Creates an empty File object.

Parameters:
ptr_file A pointer to the File structure
Returns:
A pointer to the initialized File object
       #include <cybiko.h>
       ...
       struct File file;
       ...
       File_ctor( &file );
       if( File_get_info( &file, "share_data.txt" )
           && File_is_free( &file ) )
       {
         //  Performs IO operations.
         ...
       }
       ...
       File_dtor( &file, LEAVE_MEMORY );
       ...
See also:
File_ctor_Ex.

struct File * File_ctor_Ex ( | struct File * ptr_file,
 | char * sz_file_name )

Extended version of the File_ctor function.
Creates a File object and initializes it, using the specified file's parameters.

Parameters:
ptr_file | A pointer to the File structure
sz_file_name | The name of the file with which to initialize the File object
Returns:
A pointer to the initialized File object.
       #include <cybiko.h>
       ...
       struct File file;
       ...
       File_ctor( &file, "share_data.txt" );
       if( File_is_free( &file ) )
       {
         //  Performs IO operations.
         ...
       }
       ...
       File_dtor( &file, LEAVE_MEMORY );
       ...
See also:
File_ctor.

void File_dtor ( | struct File * ptr_file,
 | int memory_flag )

Destructor.

Parameters:
ptr_file | A pointer to the initialized File object.
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cybiko.h>
       ...
       struct File file;
       ...
       File_ctor( &file );
       if( File_get_info( &file, "share_data.txt" )
           && File_is_free( &file ) )
       {
         //  Performs IO operations.
         ...
       }
       ...
       File_dtor( &file, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool File_exists ( char * sz_file_name )

Checks whether a file with specified name exists.

Parameters:
sz_file_name The file name to check.
Returns:
TRUE if the file with the specified name exists, otherwise FALSE
       #include <cybiko.h>
       ...
       if( File_exists( "save.dat" ) )
       {
         //  Load unfinished game.
         ...
       }
       ...
       if( game_finished )
       {
         File_remove( "save.dat" );
       }
       ...

long File_files_total ( char * sz_device_name )

Returns the total number of files on the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
The total number of files on the specified device
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...
See also:
File_bytes_total.

long File_free_blocks_total ( char * sz_device_name )

Returns the number of free blocks on the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
The number of free blocks on the specified device
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...

long File_free_bytes_total ( char * sz_device_name )

Estimates the number of free bytes on the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
Number of free bytes on the specified device
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...
See also:
File_free_user_bytes_total.

long File_free_user_bytes_total ( char * sz_device_name )

Estimates the number of free bytes for user data on the specified device.

Parameters:
sz_device_name The device name (or "" for local flash memory)
Returns:
Number of free bytes on the specified device for user data
       #include <cybiko.h>
       ...
       TRACE( "------Flash Info---------" );
       TRACE( "Bytes total on your device : %ld ", File_bytes_total( "" ) );
       TRACE( "Block size : %ld ", File_block_size( "" ) );
       TRACE( "Blocks total on your device : %ld ", File_blocks_total( "" ) );
       TRACE( "Free blocks total on your device : %ld ", File_free_blocks_total( "" ) );
       TRACE( "Bad blocks total on your device : %ld ", File_bad_blocks_total( "" ) );
       TRACE( "Free bytes total on your device : %ld ", File_free_bytes_total( "" ) );
       TRACE( "Free bytes for user needs on your device : %ld ", File_free_user_bytes_total( "" ) );
       TRACE( "File number on your device  : %ld ", File_files_total( "" ) );
       TRACE( "Device is %s ", File_bootable("") ? "bootable" : "not bootable" );
       ...
See also:
File_free_bytes_total.

time_t File_get_date ( struct File * ptr_file )

Returns the time the file was last modified.

Parameters:
ptr_file A pointer to the initialized File object
Returns:
The time the file was last modified
       #include <cybiko.h>
       ...
       struct File file;
       struct Time file_time;
       ...
       {
         File_ctor( &file );
         if( File_get_info( &file, "share_data.txt" )
             && File_is_free( &file ) )
         {
           Time_decode( &file_time, File_get_date( &file ) );
           TRACE("Date of modification is  %d.%d.%d",
                  file_time.month,
                  file_time.day,
                  file_time.year + 1990 );
         }
         ...
         File_dtor( &file, LEAVE_MEMORY );
       }
       ...
See also:
File_set_date.

bool File_get_info ( | struct File * ptr_file,
 | char * sz_file_name )

Initializes the File object's fields (name, date, length) of the File object, using the specified file's parameters.

Parameters:
ptr_file | A pointer to the initialized File object
sz_file_name | The name of the file with which to initialize the File object
Returns:
FALSE if the file is not found
       #include <cybiko.h>
       ...
       struct File file;
       ...
       File_ctor( &file );
       if( File_get_info( &file, "share_data.txt" )
           && File_is_free( &file ) )
       {
         //  Performs IO operations.
         ...
       }
       ...
       File_dtor( &file, LEAVE_MEMORY );
       ...

bool File_is_free ( struct File * ptr_file )

Checks whether a file is open for IO functions.

Parameters:
ptr_file A pointer to the initialized File object
Returns:
TRUE if the file is open for IO functions
       #include <cybiko.h>
       ...
       struct File file;
       ...
       File_ctor( &file );
       if( File_get_info( &file, "share_data.txt" )
           && File_is_free( &file ) )
       {
         //  Performs IO operations.
         ...
       }
       ...
       File_dtor( &file, LEAVE_MEMORY );
       ...

bool File_is_valid_name ( char * sz_file_name )

Returns TRUE if the specified string is valid as a filename.

Parameters:
sz_file_name The file's name
Returns:
TRUE if the specified string is valid as a file name
       #include <cybiko.h>
       ...
       char* input_new_file_name();
       ...
       if( File_is_valid_name( input_new_file_name() ) )
       {
         //  Creating new file.
         ...
       }
       ...

bool File_remove ( char * sz_file_name )

Deletes the specified file if it is not being modified (written to or read).

Parameters:
sz_file_name The file's name
Returns:
TRUE if the file is successfully removed, otherwise FALSE
       #include <cybiko.h>
       ...
       if( File_exists( "save.dat" ) )
       {
         //  Loads unfinished game.
         ...
       }
       ...
       if( game_finished )
       {
         File_remove( "save.dat" );
       }
       ...

bool File_rename ( | char * sz_old_filename,
 | char * sz_new_filename )

Renames the specified file if it is not being modified (written to or read).

Parameters:
sz_old_filename | Old file name
sz_new_filename | New file name
Returns:
TRUE if the file is successfully renamed, otherwise FALSE
       #include <cybiko.h>
       ...
       if( File_exists( "last_game.sav" ) )
       {
         File_rename( "last_game.sav", "prev_game.sav" );
       }
       ...

bool File_set_date ( | struct File * ptr_file,
 | time_t date )

Sets date the file was last modified.

Parameters:
ptr_file | A pointer to the initialized File object
date | A date the file was last modified
Returns:
TRUE if the time set was successful
       #include <cybiko.h>
       ...
       struct File file;
       ...
       File_ctor( &file );
       if( File_get_info( &file, "share_data.txt" )
           && File_is_free( &file ) )
       {
         //  Performs IO operations.
         ...
         //  Updates the date of the last modifications.
         File_set_date( &file, time() );
       }
       ...
       File_dtor( &file, LEAVE_MEMORY );
       ...
See also:
File_get_date.

Member Data Documentation

time_t modification_time

Time of the last modification.

char name[MAX_NAME_LEN]

File name.

long size

File size.


FileFind Struct Reference

Public Methods
struct FileFind* | FileFind_ctor (struct FileFind *ptr_file_find, struct File *ptr_file_info, char *sz_mask)
bool | FileFind_has_more_elements (struct FileFind *ptr_file_find)
void | FileFind_init (struct FileFind *ptr_file_find, struct File *ptr_file_info, char *sz_mask)
struct File* | FileFind_next_element (struct FileFind *ptr_file_find)
void | FileFind_dtor (struct FileFind *ptr_file_find, int memory_flag)

Detailed Description

Implements the functions needed to find a set of files.

See also:
File I/O

Member Function Documentation

struct FileFind * FileFind_ctor ( | struct FileFind * ptr_file_find,
 | struct File * ptr_file_info,
 | char * sz_mask )

Starts a new search session using a specified search mask.

Parameters:
ptr_file_find | A pointer to the FileFind structure
ptr_file_info | A pointer the initialized File object to store the result
sz_mask | File search mask (symbols '*' and '?' supported)
Returns:
A pointer to the initialized FileFind object
       #include <cybiko.h>
       ...
       struct FileFind searcher;
       struct File file_info;
       ...
       File_ctor( &file_info );
       FileFind_ctor( &searcher, &file_info, "quake.*" );
       ...
       TRACE( "Search results:" );
       do
       {
         FileFind_next_element( &searcher );
         TRACE( "\t%s has size %ld", file_info.name, file_info.size );
       }while( FileFind_has_more_elements( &searcher ) );
       ...
       File_dtor( &file_info , LEAVE_MEMORY );
       FileFind_dtor( &searcher, LEAVE_MEMORY );
       ...

void FileFind_dtor ( | struct FileFind * ptr_file_find,
 | int memory_flag )

Deletes an object.

Parameters:
ptr_file_find | A pointer to the initialized FileFind object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None.
       #include <cybiko.h>
       ...
       struct FileFind searcher;
       struct File file_info;
       ...
       FileFind_ctor( &searcher, &file_info, "quake.*" );
       File_ctor( &file_info );
       ...
       TRACE( "Search results:");
       do
       {
         FileFind_next_element( &searcher );
         TRACE( "\t%s has size %ld", file_info.name, file_info.size );
       }while( FileFind_has_more_elements( &searcher ) );
       ...
       File_dtor( &file_info, LEAVE_MEMORY );
       FileFind_dtor( &searcher , LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

bool FileFind_has_more_elements ( struct FileFind * ptr_file_find )

Checks wheter there are any elements left in the search.

Parameters:
ptr_file_find A pointer to the initialized FileFind object
Returns:
TRUE if there are any elements left in the search, otherwise FALSE
       #include <cybiko.h>
       ...
       struct FileFind searcher;
       struct File file_info;
       ...
       File_ctor( &file_info );
       FileFind_ctor( &searcher, &file_info, "quake.*" );
       ...
       TRACE("Search results:");
       do
       {
         FileFind_next_element( &searcher );
         TRACE( "\t%s has size %ld", file_info.name, file_info.size );
       }while( FileFind_has_more_elements( &searcher ) );
       ...
       File_dtor( &file_info , LEAVE_MEMORY );
       FileFind_dtor( &searcher, LEAVE_MEMORY );
       ...

void FileFind_init ( | struct FileFind * ptr_file_find,
 | struct File * ptr_file_info,
 | char * sz_mask )

Initializes the new file search session.

Parameters:
ptr_file_find | A pointer to the initialized FileFind object
ptr_file_info | A pointer to the initialized File object to store the result
sz_mask | File search mask (symbols '*' and '?' supported).
Returns:
None.
       #include <cybiko.h>
       ...
       struct FileFind searcher;
       struct File file_info;
       ...
       File_ctor( &file_info );
       FileFind_ctor( &searcher, &file_info, "quake.*" );
       ...
       TRACE( "Search results for quake :" );
       do
       {
         FileFind_next_element( &searcher );
         TRACE( "\t%s has size %ld", file_info.name, file_info.size );
       }while( FileFind_has_more_elements( &searcher ) );
       ...
       FileFind_init( &searcher, &file_info, "warcraft.*" );
       TRACE( "Search results for warcraft :" );
       do
       {
         FileFind_next_element( &searcher );
         TRACE( "\t%s has size %ld", file_info.name, file_info.size );
       }while( FileFind_has_more_elements( &searcher ) );
       ...
       File_dtor( &file_info , LEAVE_MEMORY );
       FileFind_dtor( &searcher, LEAVE_MEMORY );
       ...

struct File * FileFind_next_element ( struct FileFind * ptr_file_find )

Retrieves the next element of the file search session.

Parameters:
ptr_file_find A pointer to the initialized FileFind object
Returns:
File's address, or NULL if there are no more elements
       #include <cybiko.h>
       ...
       struct FileFind searcher;
       struct File file_info;
       ...
       FileFind_ctor( &searcher, &file_info, "quake.*" );
       ...
       TRACE( "Search results:" );
       do
       {
         FileFind_next_element( &searcher );
         TRACE( "\t%s has size %ld", file_info.name, file_info.size );
       }while( FileFind_has_more_elements( &searcher ) );
       ...
       File_dtor( &file_info , LEAVE_MEMORY );
       FileFind_dtor( &searcher, LEAVE_MEMORY );
       ...


FileInput Struct Reference

Inheritance diagram for FileInput

Collaboration diagram for FileInput:

Public Methods
struct FileInput* | FileInput_ctor (struct FileInput *ptr_file_input)
struct FileInput* | FileInput_ctor_Ex (struct FileInput *ptr_file_input, char *sz_file_name)
bool | FileInput_open (struct FileInput *ptr_file_input, char *sz_file_name)
long | FileInput_seek (struct FileInput *ptr_file_input, long pos, seek_t mode)
long | FileInput_tell (struct FileInput *ptr_file_input)
void | FileInput_dtor (struct FileInput *ptr_file_input, int memory_flag)
long | FileInput_read (struct FileInput *ptr_file_input, void *ptr_buffer, long length)
int | FileInput_read_byte (struct FileInput *ptr_file_input)
long | FileInput_seekg (struct FileInput *ptr_file_input, long pos, seek_t mode)
long | FileInput_tellg (struct FileInput *ptr_file_input)
long | FileInput_get_size (struct FileInput *ptr_file_input)
int | FileInput_get_flags (struct FileInput *ptr_file_input)
bool | FileInput_is_eof (struct FileInput *ptr_file_input)
bool | FileInput_is_bad (struct FileInput *ptr_file_input)
bool | FileInput_is_good (struct FileInput *ptr_file_input)

Detailed Description

Implements basic file input operations. Attempting to open or construct FileInput for a non-existing file will corrupt the file (FileInput_is_bad returns TRUE)

See also:
File I/O

Member Function Documentation

struct FileInput * FileInput_ctor ( struct FileInput * ptr_file_input )

Creates an empty input file stream object.

Parameters:
ptr_file_input A pointer to the FileInput structure
Returns:
A pointer to the initialized FileInput object.
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
         ...
       }
See also:
FileInput_ctor_Ex.

struct FileInput * FileInput_ctor_Ex ( | struct FileInput * ptr_file_input,
 | char * sz_file_name )

Creates an input file stream object for a file with the specified name.

Parameters:
ptr_file_input | A pointer to the FileInput structure
sz_file_name | Name of the file to open
Returns:
A pointer to the initialized FileInput object
       #include <cybiko.h>
       ...
       char tenth_byte;
       struct FileInput file_input;
       ...
       FileInput_ctor_Ex( &file_input, "game.save");
       ...
       FileInput_seek( &file_input, 10, SEEK_SET );
       tenth_byte = FileInput_read_byte( &file_input );
       ...
       FileInput_dtor( &file_input, LEAVE_MEMORY );
       ...
See also:
FileInput_ctor.

void FileInput_dtor ( | struct FileInput * ptr_file_input,
 | int memory_flag )

Destructor.

Parameters:
ptr_file_input | A pointer to the initialized FileInput object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY

int FileInput_get_flags ( struct FileInput * ptr_file_input )

Returns the stream's current state.

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
The stream's current state
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long size;
         long sum = 0;
         long index = 0;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "values.txt" ) )
         {
           while( ! ( FileInput_get_flags( &file_input ) & FLAG_EOF ) )
           {
             sum += (long)FileInput_read_byte( &file_input );
             index ++;
           }
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
Flags

long FileInput_get_size ( struct FileInput * ptr_file_input )

Returns the stream size (if applicable).

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
Stream size, or -1 if this operation can't be done on this stream
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long size;
         long index;
         long sum = 0;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "values.txt" ) )
         {
           size = FileInput_get_size( &file_input);
           for( index = 0; index < size; index++ )
           {
             sum += (long)FileInput_read_byte( &file_input );
           }
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...

bool FileInput_is_bad ( struct FileInput * ptr_file_input )

Returns TRUE if the BAD flag is set (stream is bad).

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
TRUE if the BAD flag is set (stream is bad)
       #include <cybiko.h>
       ...
       struct FileInput file_input;
       ...
       FileInput_ctor_Ex( &file_input , "values.txt");
       if ( ! FileInput_is_bad( &file_input ) )
       {
         //  Success.
         ...
       }
       ...
See also:
Flags

bool FileInput_is_eof ( struct FileInput * ptr_file_input )

Returns TRUE if the EOF flag is set (stream reached end-of-file).

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file)
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long size;
         long sum = 0;
         long index = 0;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "values.txt" ) )
         {
           while( ! FileInput_is_eof( &file_input ) )
           {
             sum += (long)FileInput_read_byte( &file_input );
             index ++;
           }
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...

bool FileInput_is_good ( struct FileInput * ptr_file_input )

Returns TRUE if the BAD flag is not set (stream is good).

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
TRUE if the BAD flag is not set (stream is good).
       #include <cybiko.h>
       ...
       struct FileInput file_input;
       ...
       FileInput_ctor_Ex( &file_input , "values.txt");
       if( FileInput_is_good( &file_input ) )
       {
         //  Success.
         ...
       }
       ...
See also:
Flags

bool FileInput_open ( | struct FileInput * ptr_file_input,
 | char * sz_file_name )

Opens an input stream for the file with the specified name.

Parameters:
ptr_file_input | A pointer to the initialized FileInput object
sz_file_name | Name of the file to open
Returns:
TRUE if the stream was opened successfully
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...

long FileInput_read ( | struct FileInput * ptr_file_input,
 | void * ptr_buffer,
 | long length )

Reads a specified number of bytes from the stream.

Parameters:
ptr_file_input | A pointer to the initialized FileInput object
ptr_buffer | A pointer to the allocated buffer
length | The number of bytes to read
Returns:
The exact number of bytes read, or 0 if no bytes were read
       #include <cybiko.h>
       ...
       struct FileInput file_input;
       struct score_t high_scores[10];
       ...
       FileInput_ctor( &file_input );
       if( FileInput_open( &file_input, "game.save" ) )
       ...
       Input_read( &file_input, high_scores, sizeof(high_scores) );
       ...
       Input_dtor( &file_input, LEAVE_MEMORY );
       ...
See also:
FileInput_read_byte.

int FileInput_read_byte ( struct FileInput * ptr_file_input )

Reads the next byte from the stream.

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
The next byte from the stream
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
FileInput_read.

long FileInput_seek ( | struct FileInput * ptr_file_input,
 | long pos,
 | seek_t mode )

Seeks to the specified position, then returns the sought position.
If the stream supports a seek operation, it seeks to the specified position in the specified mode. If the requested seek operation can not be done (not supported or wrong parameters), -1 will be returned. Seeking prior to the beginning of the stream sets the pointer to the stream's first byte. Seeking after the end of the stream sets the pointer to the end of stream just after the stream's last byte.

Parameters:
ptr_file_input | A pointer to the initialized FileInput object
pos | The seek offset
mode | The seek mode
Returns:
The new position, or -1 if an error occurred
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seek( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileInput_seekg ( | struct FileInput * ptr_file_input,
 | long pos,
 | seek_t mode )

Seeks an input stream.

Parameters:
ptr_file_input | A pointer to the initialized FileInput object
pos | The seek offset
mode | The seek mode
Returns:
The new position, or -1 if an error occurred
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seekg( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileInput_tell ( struct FileInput * ptr_file_input )

Returns the stream's current position.

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
The stream's position, or -1 if that operation is not supported for this stream
       #include <cybiko.h>
       ...
       char tenth_byte;
       struct FileInput file_input;
       long cur_pos;
       ...
       FileInput_ctor_Ex( &file_input, "game.save");
       ...
       FileInput_seek( &file_input, 10, SEEK_SET );
       tenth_byte = FileInput_read_byte( &file_input );
       // cur_pos will be equal to 11.
       cur_pos = FileInput_tell( &file_input );
       ...
       FileInput_dtor( &file_input, LEAVE_MEMORY );
       ...

long FileInput_tellg ( struct FileInput * ptr_file_input )

Returns the stream's position.

Parameters:
ptr_file_input A pointer to the initialized FileInput object
Returns:
The stream's position
       #include <cybiko.h>
       ...
       {
         char tenth_byte;
         long current_pos;
         struct FileInput file_input;
         ...
         FileInput_ctor( &file_input );
         ...
         if( FileInput_open( &file_input, "game.save" ) )
         {
           FileInput_seekg( &file_input, 10, SEEK_SET );
           tenth_byte = FileInput_read_byte( &file_input );
         }
         //  The current_pos value will be equal to 11.
         current_pos = FileInput_tellg( &file_input );
         ...
         FileInput_dtor( &file_input, LEAVE_MEMORY );
       }
       ...


FileOutput Struct Reference

Inheritance diagram for FileOutput

Collaboration diagram for FileOutput:

Public Methods
struct FileOutput* | FileOutput_ctor (struct FileOutput *ptr_file_output)
struct FileOutput* | FileOutput_ctor_Ex (struct FileOutput *ptr_file_output, char *sz_file_name, bool create)
bool | FileOutput_open (struct FileOutput *ptr_file_output, char *sz_file_name, bool create)
long | FileOutput_seek (struct FileOutput *ptr_file_output, long pos, seek_t mode)
long | FileOutput_tell (struct FileOutput *ptr_file_output)
bool | FileOutput_truncate (struct FileOutput *ptr_file_output, long position)
void | FileOutput_dtor (struct FileOutput *ptr_file_output, int memory_flag)
long | FileOutput_write (struct FileOutput *ptr_file_output, void *ptr_buffer, long length)
int | FileOutput_write_byte (struct FileOutput *ptr_file_output, int fbyte)
long | FileOutput_seekp (struct FileOutput *ptr_file_output, long pos, seek_t mode)
long | FileOutput_tellp (struct FileOutput *ptr_file_output)
long | FileOutput_get_size (struct FileOutput *ptr_file_output)
int | FileOutput_get_flags (struct FileOutput *ptr_file_output)
bool | FileOutput_is_eof (struct FileOutput *ptr_file_output)
bool | FileOutput_is_bad (struct FileOutput *ptr_file_output)
bool | FileOutput_is_good (struct FileOutput *ptr_file_output)

Detailed Description

Implements basic file output operations.

See also:
File I/O

Member Function Documentation

struct FileOutput * FileOutput_ctor ( struct FileOutput * ptr_file_output )

Creates an empty output file stream object.

Parameters:
ptr_file_output A pointer to the FileInput structure
Returns:
A pointer to the initialized FileOutput object
       #include <cybiko.h>
       ...
       {
         char tenth_byte = 100;
         struct FileOutput file_output;
         ...
         FileOutput_ctor( &file_output );
         ...
         if( FileOutput_open( &file_output, "game.save", TRUE ) )
         {
           FileOutput_seek( &file_output, 10, SEEK_SET );
           FileOutput_write_byte( &file_output, tenth_byte);
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...

struct FileOutput * FileOutput_ctor_Ex ( | struct FileOutput * ptr_file_output,
 | char * sz_file_name,
 | bool create )

Creates an output file stream object for the file with the specified name.

Parameters:
ptr_file_output | A pointer to the FileInput structure
sz_file_name | The file's name
create | Specifies whether or not to create a new file if the specified file does not exist
Returns:
A pointer to the initialized FileOutput object
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" , TRUE);
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...

void FileOutput_dtor ( | struct FileOutput * ptr_file_output,
 | int memory_flag )

Destructor.

Parameters:
ptr_file_output | A pointer to the initialized FileOutput object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" , TRUE);
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int FileOutput_get_flags ( struct FileOutput * ptr_file_output )

Returns the stream's current state.

Parameters:
ptr_file_output A pointer to the initialized FileOutput object
Returns:
The stream's current state
       #include <cybiko.h>
       ...
       char obtain_new_value();
       ...
       {
         struct FileOutput file_output;
         char current_value;
         long size;
         ...
         FileOutput_ctor_Ex( &file_output, "game.save" );
         ...
         while( !( FileOutput_get_flags( &file_output ) & FLAG_EOF ) )
         {
           current_value = obtain_new_value();
           FileOutput_write_byte(& file_output, current_value );
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...
See also:
Flags

long FileOutput_get_size ( struct FileOutput * ptr_file_output )

Returns the stream size (if applicable).

Parameters:
ptr_file_output A pointer to the initialized FileOutput object
Returns:
The stream size (if applicable)
       #include <cybiko.h>
       ...
       char obtain_new_value();
       ...
       {
         struct FileOutput file_output;
         char current_value;
         long size;
         ...
         FileOutput_ctor_Ex( &file_output, "game.save" );
         ...
         size = Output_get_size( &file_output );
         for( index = 0; index < size; index++ )
         {
           current_value = obtain_new_value();
           FileOutput_write_byte( &file_output, current_value );
         }
         cur_pos = FileOutput_tellp(&file_output);
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...

bool FileOutput_is_bad ( struct FileOutput * ptr_file_output )

Returns TRUE if the BAD flag is set (stream is bad).

Parameters:
ptr_file_output A pointer to the initialized FileOutput object
Returns:
TRUE if the BAD flag is set (stream is bad)
       #include <cybiko.h>
       ...
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       if( ! FileOutput_is_bad( &file_output ) )
       {
          //  Success.
       }
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
Flags

bool FileOutput_is_eof ( struct FileOutput * ptr_file_output )

Returns TRUE if the EOF flag is set (stream reached end-of-file).

Parameters:
ptr_file_output A pointer to the initialized FileOutput object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file)
       #include <cybiko.h>
       ...
       char obtain_new_value();
       ...
       {
         struct FileOutput file_output;
         char current_value;
         long size;
         ...
         FileOutput_ctor_Ex( &file_output, "game.save" );
         ...
         while( !( FileOutput_is_eof( &file_output ) ) )
         {
           current_value = obtain_new_value();
           FileOutput_write_byte( &file_output, current_value );
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...
See also:
Flags

bool FileOutput_is_good ( struct FileOutput * ptr_file_output )

Returns TRUE if the BAD flag is not set (stream is good).

Parameters:
ptr_file_output A pointer to the initialized FileOutput object
Returns:
TRUE if the BAD flag is not set (stream is good)
       #include <cybiko.h>
       ...
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       if( FileOutput_is_good( &file_output ) )
       {
         //  Success.
       }
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
Flags

bool FileOutput_open ( | struct FileOutput * ptr_file_output,
 | char * sz_file_name,
 | bool create )

Opens an output stream for the file with the specified name.

Parameters:
ptr_file_output | A pointer to the initialized FileOutput object
sz_file_name | The name of the file
create | Specifies whether or not to create a new file if the specified file does not exist
Returns:
TRUE if the function succeeded
       #include <cybiko.h>
       ...
       {
         char tenth_byte = 100;
         struct FileOutput file_output;
         ...
         FileOutput_ctor( &file_output );
         ...
         if( FileOutput_open( &file_output, "game.save", TRUE ) )
         {
           FileOutput_seek( &file_output, 10, SEEK_SET );
           FileOutput_write_byte( &file_output, tenth_byte);
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...

long FileOutput_seek ( | struct FileOutput * ptr_file_output,
 | long pos,
 | seek_t mode )

Seeks to the specified position, then returns the sought position.
If the stream supports a seek operation, it seeks to the specified position in the specified mode. If the requested seek operation cannot be done (not supported or wrong parameters), -1 will be returned. Seeking prior to the beginning of the stream sets the pointer to the stream's first byte. Seeking after the end of the stream sets the pointer to the end of the stream; then the stream will be extended with garbage bytes to the specified size.

Parameters:
ptr_file_output | A pointer to the initialized FileOutput object
pos | The seek offset
mode | The seek mode
Returns:
The new position, or -1 if an error occurred
       #include <cybiko.h>
       ...
       {
         char tenth_byte = 100;
         struct FileOutput file_output;
         ...
         FileOutput_ctor( &file_output );
         ...
         if( FileOutput_open( &file_output, "game.save", TRUE ) )
         {
           FileOutput_seek( &file_output, 10, SEEK_SET );
           FileOutput_write_byte( &file_output, tenth_byte);
         }
         ...
         FileOutput_dtor( &file_output, LEAVE_MEMORY );
       }
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileOutput_seekp ( | struct FileOutput * ptr_file_output,
 | long pos,
 | seek_t mode )

Seeks an output stream.

Parameters:
ptr_file_output | A pointer to the initialized FileOutput object
pos | The seek offset
mode | The seek mode
Returns:
The new position, or -1 if an error occurred
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       ...
       FileOutput_seekp( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileOutput_tell ( struct FileOutput * ptr_file_output )

Returns the stream's position.

Parameters:
ptr_file_output A pointer to the initialized FileOutput object.
Returns:
The stream's position, or -1 if the operation is not supported for this stream.
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       long cur_pos;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save", TRUE );
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       // cur_pos will be equal to 11.
       cur_pos = FileOutput_tell( &file_output );
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

long FileOutput_tellp ( struct FileOutput * ptr_file_output )

Returns the stream's position.

Parameters:
ptr_file_output A pointer to the initialized FileOutput object
Returns:
The stream position, or -1 if the operation is not supported for this stream
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       long cur_pos;
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save" );
       ...
       FileOutput_seekp( &file_output, 10, SEEK_SET );
       FileOutput_write_byte( &file_output, tenth_byte);
       //  cur_pos will be equal to 11.
       cur_pos = FileOutput_tellp( &file_output );
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...
See also:
SEEK_SET, SEEK_CUR, SEEK_END.

bool FileOutput_truncate ( | struct FileOutput * ptr_file_output,
 | long position )

Truncates a file associated with the stream.
Thread right access sensitive!

Parameters:
ptr_file_output | A pointer to the initialized FileOutput object
position | The truncation position
Returns:
TRUE if the function succeeded
       #include <cybiko.h>
       ...
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save", TRUE );
       ...
       FileOutput_seek( &file_output, 10, SEEK_SET );
       // The file size is 11 bytes now.
       FileOutput_truncate( &file_output , 10 );
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...

long FileOutput_write ( | struct FileOutput * ptr_file_output,
 | void * ptr_buffer,
 | long length )

Writes the specified number of bytes to the stream.

Parameters:
ptr_file_output | A pointer to the initialized FileOutput object
ptr_buffer | The buffer with the data to write
length | The number of bytes to write
Returns:
The exact number of bytes written, or 0 if no bytes were written
       #include <cybiko.h>
       ...
       struct score_t high_scores[10];
       struct FileOutput file_output;
       ...
       FileOutput_ctor_Ex( &file_output, "game.save", TRUE );
       ...
       FileOutput_write(&file_output, high_scores, sizeof( high_scores ));
       ....
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...

int FileOutput_write_byte ( | struct FileOutput * ptr_file_output,
 | int fbyte )

Writes a byte to the stream.

Parameters:
ptr_file_output | A pointer to the initialized FileOutput object
fbyte | The byte to write
Returns:
-1 in the case of failure, otherwise the value of the byte written
       #include <cybiko.h>
       ...
       char tenth_byte = 100;
       struct FileOutput file_output;
       ...
       FileOutput_ctor( &file_output );
       ...
       if( FileOutput_open( &file_output, "game.save", TRUE ) )
       {
         FileOutput_seek( &file_output, 10, SEEK_SET );
         FileOutput_write_byte( &file_output, tenth_byte);
       }
       ...
       FileOutput_dtor( &file_output, LEAVE_MEMORY );
       ...


Input Struct Reference

Inheritance diagram for Input

Public Methods
long | Input_seekg (struct Input *ptr_input, long pos, seek_t mode)
long | Input_tellg (struct Input *ptr_input)
long | Input_read (struct Input *ptr_input, void *buffer, long length)
int | Input_read_byte (struct Input *ptr_input)
int | Input_get_flags (struct Input *ptr_input)
bool | Input_is_eof (struct Input *ptr_input)
bool | Input_is_bad (struct Input *ptr_input)
bool | Input_is_good (struct Input *ptr_input)
long | Input_get_size (struct Input *ptr_input)
void | Input_dtor (struct Input *ptr_input, int)
short | Input_read_word (struct Input *ptr_input)
long | Input_read_dword (struct Input *ptr_input)

Detailed Description

The CyOS stream modes have 2 basic streams that are abstractions for the sequential data access objects: Input and Output. Those streams can pump data to and from virtually any source, including disk files, network connections, console terminals and more. Those basic streams are used, in turn, with filter streams that apply specific features to some abstract streams' filters.

Typical stream implementations include the file streams FileInput and FileOutput, console streams, and various filters. Filter streams process the data from other streams.

They take the other streams' objects while constructing, and are just like regular streams themselves. Typical filters are UNICODE/ASCII conversion, text formatting streams Reader and Writer, and compression streams Compressor and Decompressor.

Filters are intended to combine the desired stream implementation with the selected filter object, to combine the features that best suit your needs. This object is just an interface for an input stream.

See also:
File I/O

Member Function Documentation

void Input_dtor ( | struct Input * ptr_input,
 | int memory_flag )

Destructor.

Parameters:
ptr_input | A pointer to the initialized Input object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cywin.h>
       ...
       char tenth_byte;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int Input_get_flags ( struct Input * ptr_input )

Returns the current flags.

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
The current flags
       #include <cywin.h>
       ...
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       while( ! ( Input_get_flags(ptr_input) & FLAG_EOF ) )
       {
         sum += (long)Input_read_byte( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

long Input_get_size ( struct Input * ptr_input )

Returns the stream size (if applicable).

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
Stream size, or -1 if the operation can't be done on this stream
       #include <cywin.h>
       ...
       long size;
       long index;
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       size = Input_get_size( ptr_input );
       for( index = 0; index < size; index++ )
       {
         sum += (long)Input_read_byte( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

bool Input_is_bad ( struct Input * ptr_input )

Returns TRUE if the BAD flag is set (stream is bad).

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
TRUE if the BAD flag is set (stream is bad)
       #include <cywin.h>
          ...
          long sum = 0;
          struct Input* ptr_input;
          ...
          ptr_input = open_resource_Ex( "values.txt" );
          if (!Input_is_bad(ptr_input))
          {
             //success
          }
           ...
          Input_dtor( ptr_input, FREE_MEMORY );
See also:
Input_is_good, Input_is_eof.

bool Input_is_eof ( struct Input * ptr_input )

Returns TRUE if the EOF flag is set (stream reached end-of-file).

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file)
       #include <cywin.h>
          ...
          long sum = 0;
          struct Input* ptr_input;
          ...
          ptr_input = open_resource_Ex( "values.txt" );
          ...
          while( ! ( Input_is_eof(ptr_input) )
          {
            sum += (long)Input_read_byte( ptr_input );
          }
          ...
          Input_dtor( ptr_input, FREE_MEMORY );
Stream size, or -1 if the operation can't be done on this stream.
See also:
Input_is_bad, Input_is_good.

bool Input_is_good ( struct Input * ptr_input )

Returns TRUE if the BAD flag is not set (stream is good).

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
TRUE if the BAD flag is not set (stream is good)
       #include <cywin.h>
          ...
          long sum = 0;
          struct Input* ptr_input;
          ...
          ptr_input = open_resource_Ex( "values.txt" );
          if (Input_is_good (ptr_input))
          {
             //success
          }
           ...
          Input_dtor( ptr_input, FREE_MEMORY );
See also:
Input_is_bad, Input_is_eof.

long Input_read ( | struct Input * ptr_input,
 | void * buffer,
 | long length )

Reads the 'length' bytes from the stream.

Parameters:
ptr_input | A pointer to the initialized Input object
buffer | A pointer to the allocated buffer
length | The number of bytes to read
Returns:
The exact number of bytes read, or 0 if no bytes were read
       #include <cywin.h>
       #include "score.h"
       ...
       struct Input* ptr_input;
       struct score_t high_scores[10];
       ...
       ptr_input = open_resource_Ex( "score.inf" );
       ...
       Input_read( ptr_input, high_scores, sizeof(high_scores) );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read_byte.

int Input_read_byte ( struct Input * ptr_input )

Reads the next byte from the stream.

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
The next byte from the stream
       #include <cywin.h>
       ...
       char tenth_byte;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read.

long Input_read_dword ( struct Input * ptr_input )

Reads a 32-bit word, independent of hardware.

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
The next 4 bytes from the stream
       #include <cywin.h>
       ...
       long size;
       long index;
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       size = Input_get_size( ptr_input )/(sizeof (long));
       for( index = 0; index < size; index++ )
       {
         sum += (long)Input_read_dword( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read_word.

short Input_read_word ( struct Input * ptr_input )

Reads a 16-bit word, independent of hardware.

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
The next 2 bytes from the stream
       #include <cywin.h>
       ...
       long size;
       long index;
       long sum = 0;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "values.txt" );
       ...
       size = Input_get_size( ptr_input )/(sizeof (int));
       for( index = 0; index < size; index++ )
       {
         sum += (long)Input_read_word( ptr_input );
       }
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...
See also:
Input_read_dword.

long Input_seekg ( | struct Input * ptr_input,
 | long pos,
 | seek_t mode )

Seeks an input stream.
If the stream supports a seek operation, it seeks to the specified position in the specified mode. If the requested seek operation cannot be done (not supported or wrong parameters), -1 will be returned. Seeking prior to the beginning of the stream sets the pointer to the stream's first byte. Seeking after the end of the stream sets the pointer to the end of the stream (after the stream's last byte).

Parameters:
ptr_input | A pointer to the initialized Input object
pos | The seek offset
mode | The seek mode
Returns:
The new position or -1 if an error occurred
       #include <cywin.h>
       ...
       char tenth_byte;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...

long Input_tellg ( struct Input * ptr_input )

Returns the stream's position.

Parameters:
ptr_input A pointer to the initialized Input object
Returns:
The stream's position, or -1 of that operation is not supported for this stream
       #include <cywin.h>
       ...
       char tenth_byte;
       long current_pos;
       struct Input* ptr_input;
       ...
       ptr_input = open_resource_Ex( "data.txt" );
       ...
       Input_seekg( ptr_input, 10, SEEK_SET );
       tenth_byte = Input_read_byte( ptr_input );
       // The current_pos value will be equal to 11.
       current_pos = Input_tellg( ptr_input );
       ...
       Input_dtor( ptr_input, FREE_MEMORY );
       ...


Output Struct Reference

Inheritance diagram for Output

Public Methods
long | Output_seekp (struct Output *ptr_output, long pos, seek_t mode)
long | Output_tellp (struct Output *ptr_output)
long | Output_write (struct Output *ptr_output, void *buffer, long length)
int | Output_write_byte (struct Output *ptr_output, int byte)
int | Output_get_flags (struct Output *ptr_output)
bool | Output_is_eof (struct Output *ptr_output)
bool | Output_is_bad (struct Output *ptr_output)
bool | Output_is_good (struct Output *ptr_output)
long | Output_get_size (struct Output *ptr_output)
void | Output_dtor (struct Output *ptr_output, int)
short | Output_write_word (struct Output *ptr_output, short word)
long | Output_write_dword (struct Output *ptr_output, long dword)

Detailed Description

The CyOS's stream modes have two basic streams that are abstractions for the sequential data access objects: Input and Output. Those streams can pump data to and from virtually any source, including disk file, network connection, console terminals and more. Those basic streams are used, in turn, with filter streams, that apply specific features to some abstract streams' filters.

Typical stream implementations include the file streams FileInput and FileOutput, console streams and various filters. Filter streams process the data from other streams. They take the other stream's objects while constructing, and are just like regular streams themselves. Typical filters are UNICODE/ASCII conversion, text formatting streams Reader and Writer and compressing streams Compressor and Decompressor.

Filters are intended to combine the desired stream implementation with the selected filter object, to combine the features that best suit your needs. This object is just an interface for an input stream.

See also:
File I/O

Member Function Documentation

void Output_dtor ( | struct Output * ptr_output,
 | int memory_flag )

Destructor.

Parameters:
ptr_output | A pointer to the initialized Output object
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int Output_get_flags ( struct Output * ptr_output )

Returns the current flags.

Parameters:
ptr_output A pointer to the initialized Output object
Returns:
Current flags
       #include <cywin.h>
       ...
       char obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char current_value;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       while( !( Output_get_flags(ptr_output) & FLAG_EOF ) )
       {
         current_value = obtain_new_value();
         Output_write_byte( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

long Output_get_size ( struct Output * ptr_output )

Returns the stream size (if applicable).

Parameters:
ptr_output A pointer to the initialized Output object
Returns:
Stream size, or -1 if the operation can't be done on this stream
       #include <cywin.h>
       ...
       char obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char current_value;
       long size;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       size = Output_get_size( ptr_output );
       for( index = 0; index < size; index++ )
       {
         current_value = obtain_new_value();
         Output_write_byte( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

bool Output_is_bad ( struct Output * ptr_output )

Returns TRUE if the BAD flag is set (stream is bad).

Parameters:
ptr_output A pointer to the initialized Output object
Returns:
TRUE if the BAD flag is set (stream is bad)
       #include <cywin.h>
       ...
       struct Output *ptr_output;
       ...
       Output_ctor_Ex(ptr_output, "game.save");
       if (!FileOutput_is_bad(ptr_output))
       {
         //success
       }
       ...
       Output_dtor( ptr_output, LEAVE_MEMORY );
See also:
Output_is_good, Output_is_eof.

bool Output_is_eof ( struct Output * ptr_output )

Returns TRUE if the EOF flag is set (stream reached end-of-file).

Parameters:
ptr_output A pointer to the initialized Output object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file)
   #include <cywin.h>
   ...
   char obtain_new_value();
   ...
   struct module_t main_module;
   struct Output* ptr_output;
   char current_value;
   ...
   ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                       "data.txt" );
   ...
   while( !( Output_is_eof(ptr_output))
   {
     current_value = obtain_new_value();
     Output_write_byte( ptr_output, current_value );
   }
   ...
   Output_dtor( ptr_output, FREE_MEMORY );
   ...
See also:
Output_is_good, Output_is_bad.

bool Output_is_good ( struct Output * ptr_output )

Returns TRUE if the BAD flag is not set (stream is good).

Parameters:
ptr_output A pointer to the initialized Output object
Returns:
TRUE if the BAD flag is not set (stream is good)
       #include <cywin.h>
       ...
       struct Output *file_output;
       ...
       Output_ctor_Ex(file_output, "game.save");
       if (FileOutput_is_good(file_output))
       {
         //success
       }
       ...
       Output_dtor( &file_output, LEAVE_MEMORY );
See also:
Output_is_eof, Output_is_bad.

long Output_seekp ( | struct Output * ptr_output,
 | long pos,
 | seek_t mode )

Seeks an output stream.
If the stream supports a seek operation, it seeks to the specified position in the specified mode. If the requested seek operation cannot be done (not supported or wrong parameters), -1 will be returned. Seeking prior to the beginning of the stream sets the pointer to the stream's first byte. Seeking after the end of the stream sets the pointer to the end of the stream; then the stream will be extended with garbage bytes to the specified size.

Parameters:
ptr_output | A pointer to the initialized Output object
pos | The seek offset
mode | The seek mode
Returns:
The new position, or -1 if an error occurred
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

long Output_tellp ( struct Output * ptr_output )

Returns the stream's position.

Parameters:
ptr_output A pointer to the initialized Output object
Returns:
The stream's position, or -1 if that operation is not supported for this stream
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       long cur_pos;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       // cur_pos will be equal to 11.
       cur_pos = Output_tellp( ptr_output );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

long Output_write ( | struct Output * ptr_output,
 | void * buffer,
 | long length )

Writes the 'length' bytes to the stream.

Parameters:
ptr_output | A pointer to the initialized Output object
buffer | Where to get the data
length | The number of bytes to be written
Returns:
The actual number of written bytes; may be less that than 'length' or even zero
       #include <cywin.h>
       #include "score.h"
       ...
       struct Input* ptr_input;
       struct score_t high_scores[10];
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       long cur_pos;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_write( ptr_output, high_scores, sizeof( high_scores ) );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write_byte.

int Output_write_byte ( | struct Output * ptr_output,
 | int byte )

Writes a byte to the stream.

Parameters:
ptr_output | A pointer to the initialized Output object
byte | Determines which byte to write
Returns:
-1 if the process fails, the parameter's value if it succeeds
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write.

long Output_write_dword ( | struct Output * ptr_output,
 | long dword )

Writes a 32-bit word, independent of hardware.

Parameters:
ptr_output | A pointer to the initialized Output object
dword | A dword to be written
Returns:
-1 if the process fails, the parameter's value if it succeeds
       #include <cywin.h>
       ...
       long obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       long current_value;
       long size;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       size = Output_get_size( ptr_output )/sizeof(long);
       for( index = 0; index < size; index++ )
       {
         current_value = obtain_new_value();
         Output_write_dword( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write_word.

short Output_write_word ( | struct Output * ptr_output,
 | short word )

Writes a 16-bit word, independent of hardware.

Parameters:
ptr_output | A pointer to the initialized Output object
word | A word to be written
Returns:
-1 if the process fails, the parameter's value if it succeeds
       #include <cywin.h>
       ...
       int obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       int current_value;
       long size;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       size = Output_get_size( ptr_output )/sizeof(int);
       for( index = 0; index < size; index++ )
       {
         current_value = obtain_new_value();
         Output_write_word( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write_dword.


Keyboard Input

Defines
#define | KEY_SECTION1 0x100
#define | KEY_SECTION2 0x101
#define | KEY_SECTION3 0x102
#define | KEY_SECTION4 0x103
#define | KEY_SECTION5 0x104
#define | KEY_SECTION6 0x105
#define | KEY_SECTION7 0x106
#define | KEY_ESC 0x107
#define | KEY_LEFT 0x108
#define | KEY_UP 0x109
#define | KEY_RIGHT 0x10A
#define | KEY_DOWN 0x10B
#define | KEY_INS 0x10C
#define | KEY_DEL 0x10D
#define | KEY_TAB 0x10E
#define | KEY_SELECT 0x10F
#define | KEY_ENTER 0x110
#define | KEY_BACKSPACE 0x111
#define | KEY_HELP 0x112
#define | KEY_SHIFT 0x113
#define | KEY_CONTROL 0x114
#define | KEY_CY 133
#define | KEY_SPACE 0x20
#define | KEY_0 0x30
#define | KEY_1 0x31
#define | KEY_2 0x32
#define | KEY_3 0x33
#define | KEY_4 0x34
#define | KEY_5 0x35
#define | KEY_6 0x36
#define | KEY_7 0x37
#define | KEY_8 0x38
#define | KEY_9 0x39
#define | KEY_QUOTE 0x27
#define | KEY_COMMA 0x2C
#define | KEY_MINUS 0x2D
#define | KEY_PERIOD 0x2E
#define | KEY_SLASH 0x2F
#define | KEY_SEMICOLON 0x3B
#define | KEY_BACKSLASH 0x5C
#define | KEY_EQUAL 0x3D
#define | KEY_OPEN_SBRACKET 0x5B
#define | KEY_CLOSE_SBRACKET 0x5D
#define | KEY_BACKQUOTE 0x60
#define | KEY_A 0x61
#define | KEY_B 0x62
#define | KEY_C 0x63
#define | KEY_D 0x64
#define | KEY_E 0x65
#define | KEY_F 0x66
#define | KEY_G 0x67
#define | KEY_H 0x68
#define | KEY_I 0x69
#define | KEY_J 0x6A
#define | KEY_K 0x6B
#define | KEY_L 0x6C
#define | KEY_M 0x6D
#define | KEY_N 0x6E
#define | KEY_O 0x6F
#define | KEY_P 0x70
#define | KEY_Q 0x71
#define | KEY_R 0x72
#define | KEY_S 0x73
#define | KEY_T 0x74
#define | KEY_U 0x75
#define | KEY_V 0x76
#define | KEY_W 0x77
#define | KEY_X 0x78
#define | KEY_Y 0x79
#define | KEY_Z 0x7A

Typedefs
typedef int | click_kind_t

Functions
bool | get_clicks_enabled (void)
void | set_clicks_enabled (bool enable)
void | disable_key_click (int *ptr_key_list, int key_count)
time_t | last_key_time (void)
click_kind_t | get_click_kind (void)
void | set_click_kind (click_kind_t kind)
bool | is_sticking_keys_enabled (void)
void | enable_sticking_keys (bool enable)
bool | enable_function_keys (bool enable)

Compounds
struct DirectKeyboard A DirectKeyboard object scans the CYBIKO keyboard to determine what keys the user has pressed

Detailed Description

Some structures, functions and defines for work with keyboard. We recommend that you look at DirectKeyboard structure. It's more difficult, but it's a more effective way to handle keyboard input (the easy way is to just process respective Message's).

Define Documentation

#define KEY_0 0x30

0 key.

#define KEY_1 0x31

1 key.

#define KEY_2 0x32

2 key.

#define KEY_3 0x33

3 key.

#define KEY_4 0x34

4 key.

#define KEY_5 0x35

5 key.

#define KEY_6 0x36

6 key.

#define KEY_7 0x37

7 key.

#define KEY_8 0x38

8 key.

#define KEY_9 0x39

9 key.

#define KEY_A 0x61

A key.

#define KEY_B 0x62

B key.

#define KEY_BACKQUOTE 0x60

` key.

#define KEY_BACKSLASH 0x5C

\ key.

#define KEY_BACKSPACE 0x111

Backspace, move left and delete.

#define KEY_C 0x63

C key.

#define KEY_CLOSE_SBRACKET 0x5D

] key.

#define KEY_COMMA 0x2C

, key.

#define KEY_CONTROL 0x114

Ctrl ( "alternative function" ) key.

#define KEY_CY 133

CY sign (Fn+C).

#define KEY_D 0x64

D key.

#define KEY_DEL 0x10D

Delete/No, 2-nd big key.

#define KEY_DOWN 0x10B

Down ( joystick, arrow key ).

#define KEY_E 0x65

E key.

#define KEY_ENTER 0x110

Enter, 5-th big key.

#define KEY_EQUAL 0x3D

= key.

#define KEY_ESC 0x107

Escape/Backspace ( upper left corner ).

#define KEY_F 0x66

F key.

#define KEY_G 0x67

G key.

#define KEY_H 0x68

H key.

#define KEY_HELP 0x112

Help key, in the upper-left corner of the case.

#define KEY_I 0x69

I key.

#define KEY_INS 0x10C

Insert/Yes, 1-st big key.

#define KEY_J 0x6A

J key.

#define KEY_K 0x6B

K key.

#define KEY_L 0x6C

L key.

#define KEY_LEFT 0x108

Left ( joystick, arrow key ).

#define KEY_M 0x6D

M key.

#define KEY_MINUS 0x2D

"-" key.

#define KEY_N 0x6E

N key.

#define KEY_O 0x6F

O key.

#define KEY_OPEN_SBRACKET 0x5B

[ key.

#define KEY_P 0x70

P key.

#define KEY_PERIOD 0x2E

"." key.

#define KEY_Q 0x71

Q key.

#define KEY_QUOTE 0x27

' key.

#define KEY_R 0x72

R key.

#define KEY_RIGHT 0x10A

Right ( joystick, arrow key ).

#define KEY_S 0x73

S key.

#define KEY_SECTION1 0x100

Hot key for section Main Menu.

#define KEY_SECTION2 0x101

Hot key for section Chat.

#define KEY_SECTION3 0x102

Hot key for section People.

#define KEY_SECTION4 0x103

Hot key for section Applications.

#define KEY_SECTION5 0x104

Hot key for section Games.

#define KEY_SECTION6 0x105

Hot key for section Labyrinth.

#define KEY_SECTION7 0x106

Hot key for section CyLandia.

#define KEY_SELECT 0x10F

Select, 4-th big key.

#define KEY_SEMICOLON 0x3B

; key.

#define KEY_SHIFT 0x113

Shift ( "upper case" ) key.

#define KEY_SLASH 0x2F

/ key.

#define KEY_SPACE 0x20

Space key.

#define KEY_T 0x74

T key.

#define KEY_TAB 0x10E

Tab/Switch, 3-rd big key.

#define KEY_U 0x75

U key.

#define KEY_UP 0x109

Up ( joystick, arrow key ).

#define KEY_V 0x76

V key.

#define KEY_W 0x77

W key.

#define KEY_X 0x78

X key.

#define KEY_Y 0x79

Y key.

#define KEY_Z 0x7A

Z key.

Typedef Documentation

typedef int click_kind_t

Keyboard click sound.
Must be one of the following: CK_NO, CK_BEEP_SHORT or CK_BEEP_SHORT.

See also:
CK_NO, CK_BEEP_SHORT, CK_BEEP_SHORT.

Function Documentation

void disable_key_click ( | int * ptr_key_list,
 | int key_count )

Disables the click sound for the keys specified, enables the click sound for the rest keys.
To enable the click sound for all the keys, call disable_key_click() with key_list and key_count set to 0.

Parameters:
ptr_key_list | an array of keys virtual codes.
key_count | the number of elements in this array.
Returns:
None.
       #include <cybiko.h>
       ...
       static const int arrows_keys[4] = {
                                           KEY_UP,
                                           KEY_DOWN,
                                           KEY_LEFT,
                                           KEY_RIGHT
                                         };
       ...
       // Disables the click sound for the arrows keys.
       disable_key_click( arrows_keys, 4 );
       ...

bool enable_function_keys ( bool enable )

Enables or disables function key processing.

Parameters:
enable if TRUE enables function key processing, else disables ones.
Returns:
Previous state.
       #include <cybiko.h>
       ...
       bool function_keys;
       ...
       //  Disables key function processing.
       function_keys = enable_function_keys(FALSE);
       ...
       //  Restores key function processing state.
       enable_function_keys(function_keys);
       ...

void enable_sticking_keys ( bool enable )

Enables or disables "sticking keys" option.

Parameters:
enable if TRUE, "sticking keys" option is enabled, else "sticking keys" option is disabled.
Returns:
None.
       #include <cybiko.h>
       ...
       if ( !is_sticking_keys_enabled() )
          enable_sticking_keys( TRUE );
See also:
is_sticking_keys_enabled.

click_kind_t get_click_kind ( void )

Returns current kind of click sound.

Returns:
The current kind of click sound.
       #include <cybiko.h>
       ...
       click_kind_t click_type;
       ...
       click_type = get_click_kind();
       // 'click_type' might have parameters as follows: CK_BEEP_SHORT, CK_BEEP, CK_NO.
       if ( click_type != CK_BEEP_SHORT )
            set_click_kind( CK_BEEP_SHORT );
       ...
See also:
set_click_kind, CK_BEEP_SHORT, CK_BEEP, CK_NO.

bool get_clicks_enabled ( void )

Returns state of a key clicks prohibition.

Returns:
TRUE if the key click is not prohibited.
       #include <cybiko.h>
       ...
       bool clicks_enabled;
       ...
       clicks_enabled = get_clicks_enabled();
       // Turns off the keys clicks.
       set_clicks_enabled( FALSE );
       ...
       // Restors the keys clicks.
       set_clicks_enabled( clicks_enabled );
See also:
set_clicks_enabled.

bool is_sticking_keys_enabled ( void )

Returns TRUE if "sticking keys" option is enabled.

Returns:
TRUE if "sticking keys" option is enabled.
       #include <cybiko.h>
       ...
       if ( !is_sticking_keys_enabled() )
          enable_sticking_keys( TRUE );
See also:
enable_sticking_keys.

time_t last_key_time ( void )

Returns the time (in the time_t format) of the last keystroke.

Returns:
The last keystroke time.
       #include <cybiko.h>
       ...
       struct Time time;
       ...
       Time_decode( &time, last_key_time() );
       TRACE("Last key was pressed at hour: %d, minutes: %d, seconds: %d",
              time.hour, time.minute, time.second );
       ...

void set_click_kind ( click_kind_t kind )

Sets current kind of click sound.

Parameters:
kind must be one of the following: CK_NO, CK_BEEP, or CK_BEEP_SHORT.
Returns:
None.
       #include <cybiko.h>
       ...
       click_kind_t click_type;
       ...
       click_type = get_click_kind();
       // 'click_type' might have parameters as follows: CK_BEEP_SHORT, CK_BEEP, CK_NO.
       if ( click_type != CK_BEEP_SHORT )
            set_click_kind( CK_BEEP_SHORT );
       ...
See also:
get_click_kind, CK_BEEP_SHORT, CK_BEEP, CK_NO.

void set_clicks_enabled ( bool enable )

Disables or enables keyboard clicks.

Parameters:
enable if TRUE enables all keyboard clicks, else disables keyboard clicks in accordance to procedure disable_key_click().
Returns:
None.
       #include <cybiko.h>
       ...
       bool clicks_enabled;
       ...
       clicks_enabled = get_clicks_enabled();
       // Turns off the keys clicks.
       set_clicks_enabled( FALSE );
       ...
       // Restors the keys clicks.
       set_clicks_enabled( clicks_enabled );
See also:
get_clicks_enabled.


DirectKeyboard Struct Reference

Public Methods
void | DirectKeyboard_dtor (struct DirectKeyboard *ptr_direct_keyboard, int memory_flag)
struct DirectKeyboard* | DirectKeyboard_get_instance (void)
void | DirectKeyboard_scan (struct DirectKeyboard *ptr_direct_keyboard)
bool | DirectKeyboard_is_key_pressed (struct DirectKeyboard *ptr_direct_keyboard, short scancode)

Detailed Description

Use a DirectKeyboard object to scan the CYBIKO keyboard and determine what keys are being pressed. You must call the DirectKeyboard_get_instance() function before use and the DirectKeyboard_dtor() function after use.

See also:
Keyboard Input

Member Function Documentation

void DirectKeyboard_dtor ( | struct DirectKeyboard * ptr_direct_keyboard,
 | int memory_flag )

Deletes a DirectKeyboard object.

Parameters:
ptr_direct_keyboard | A pointer to the initialized DirectKeyboard object
memory_flag | THE MEMORY FLAG MUST BE FREE_MEMORY.
Returns:
None.
       #include <cybiko.h>
       ...
       struct DirectKeyboard* ptr_direct_keyboard;
       ptr_direct_keyboard = DirectKeyboard_get_instance();
       ...
       DirectKeyboard_scan( ptr_direct_keyboard );
       if ( DirectKeyboard_is_key_pressed( ptr_direct_keyboard, KEY_ESC ) )
       ...
       DirectKeyboard_dtor( ptr_direct_keyboard, FREE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct DirectKeyboard * DirectKeyboard_get_instance ( void )

Initializes a DirectKeyboard object.

Returns:
A pointer to the initialized DirectKeyboard object
       #include <cybiko.h>
       ...
       struct DirectKeyboard* ptr_direct_keyboard;
       ptr_direct_keyboard = DirectKeyboard_get_instance();
       ...
       DirectKeyboard_scan( ptr_direct_keyboard );
       if ( DirectKeyboard_is_key_pressed( ptr_direct_keyboard, KEY_ESC ) )
       ...
       DirectKeyboard_dtor( ptr_direct_keyboard, FREE_MEMORY );
       ...

bool DirectKeyboard_is_key_pressed ( | struct DirectKeyboard * ptr_direct_keyboard,
 | short scancode )

Checks whether a specified key is being pressed.
The DirectKeyboard_scan function must be called before using this function!

Parameters:
ptr_direct_keyboard | A pointer to the initialized DirectKeyboard object
scancode | The scancode of the tested key
Returns:
TRUE if the specified key is pressed
       #include <cybiko.h>
       ...
       struct DirectKeyboard* ptr_direct_keyboard;
       ptr_direct_keyboard = DirectKeyboard_get_instance();
       ...
       DirectKeyboard_scan( ptr_direct_keyboard );
       if( DirectKeyboard_is_key_pressed( ptr_direct_keyboard, KEY_ESC ) )
       ...
       DirectKeyboard_dtor( ptr_direct_keyboard, FREE_MEMORY );
See also:
DirectKeyboard_scan

void DirectKeyboard_scan ( struct DirectKeyboard * ptr_direct_keyboard )

Scans the CYBIKO keyboard to determine what keys are being pressed.

Parameters:
ptr_direct_keyboard A pointer to the initialized DirectKeyboard object
Returns:
None.
       #include <cybiko.h>
       ...
       struct DirectKeyboard* ptr_direct_keyboard;
       ptr_direct_keyboard = DirectKeyboard_get_instance();
       ...
       DirectKeyboard_scan( ptr_direct_keyboard );
       if ( DirectKeyboard_is_key_pressed( ptr_direct_keyboard, KEY_ESC ) )
       ...
       DirectKeyboard_dtor( ptr_direct_keyboard, FREE_MEMORY );
       ...
See also:
DirectKeyboard_is_key_pressed


Serial Port Access

Enumerations
enum | com_dev_t { COMM_DEV_DEFAULT }
enum {
COMM_BAUD_110,
COMM_BAUD_300,
COMM_BAUD_600,
COMM_BAUD_1200,
COMM_BAUD_2400,
COMM_BAUD_4800,
COMM_BAUD_7200,
COMM_BAUD_9600,
COMM_BAUD_14400,
COMM_BAUD_19200,
COMM_BAUD_38400,
COMM_BAUD_57600,
COMM_BAUD_115200
}
enum {
COMM_DATABITS_5,
COMM_DATABITS_6,
COMM_DATABITS_7,
COMM_DATABITS_8
}
enum {
COMM_STOPBITS_10,
COMM_STOPBITS_15,
COMM_STOPBITS_20
}
enum {
COMM_PARITY_NONE,
COMM_PARITY_ODD,
COMM_PARITY_EVEN,
COMM_PARITY_MARK,
COMM_PARITY_SPACE
}
enum {
COMM_FC_NONE = 0x00,
COMM_FC_XONXOFF_INPUT = 0x01,
COMM_FC_XONXOFF_OUTPUT = 0x02,
COMM_FC_RTSCTS_INPUT = 0x04,
COMM_FC_RTSCTS_OUTPUT = 0x08,
COMM_FC_DSRDTR_INPUT = 0x10,
COMM_FC_DSRDTR_OUTPUT = 0x20
}
enum WaitResult {
COMM_WAIT_TIMEOUT,
COMM_WAIT_DATAREADY,
COMM_WAIT_ERROR
}
enum {
COMM_ERROR_GENERAL = 0x01,
COMM_ERROR_OVERRUN = 0x02,
COMM_ERROR_PARITY = 0x04,
COMM_ERROR_FRAMING = 0x08,
COMM_ERROR_TIMEOUT = 0x10,
COMM_STATE_CHANGED = 0x80
}

Functions
com_t | com_open (com_dev_t device, long timeout)
bool | com_close (com_t port)
int | com_read (com_t port, long timeout)
bool | com_write (com_t port, int value, long timeout)
int | com_wait_for_data (com_t port, long timeout)
bool | com_set_config (com_t port, struct COMMConfig *config)
bool | com_get_config (com_t port, struct COMMConfig *config)
int | com_get_state (com_t port)
bool | com_flush (com_t port)
bool | com_set_DTR (com_t port, bool state)
bool | com_set_RTS (com_t port, bool state)
bool | com_get_DTR (com_t port)
bool | com_get_RTS (com_t port)

Compounds
struct COMMConfig COM port configuration parameters COM port configuration parameters

Detailed Description

Functions for working with com port. Please see the respective Accessing Serial Port tutorial.

Enumeration Type Documentation

anonymous enum

Baud Rates.

Enumeration values:
COMM_BAUD_110 | 100 baud.
COMM_BAUD_300 | 300 baud.
COMM_BAUD_600 | 600 baud.
COMM_BAUD_1200 | 1200 baud.
COMM_BAUD_2400 | 2400 baud.
COMM_BAUD_4800 | 4800 baud.
COMM_BAUD_7200 | 7200 baud.
COMM_BAUD_9600 | 9600 baud.
COMM_BAUD_14400 | 14400 baud.
COMM_BAUD_19200 | 19200 baud.
COMM_BAUD_38400 | 38400 baud.
COMM_BAUD_57600 | 57600 baud (default).
COMM_BAUD_115200 | 115200 baud.

anonymous enum

Number of data bits per byte.

Enumeration values:
COMM_DATABITS_5 | 5 bits.
COMM_DATABITS_6 | 6 bits.
COMM_DATABITS_7 | 7 bits.
COMM_DATABITS_8 | 8 bits.

anonymous enum

Number of stop bits after byte.

Enumeration values:
COMM_STOPBITS_10 | 1 bit.
COMM_STOPBITS_15 | 1.5 bits.
COMM_STOPBITS_20 | 2 bits.

anonymous enum

Parity check.

Enumeration values:
COMM_PARITY_NONE | No flow control.
COMM_PARITY_ODD | Odd.
COMM_PARITY_EVEN | Even.
COMM_PARITY_MARK | Mark.
COMM_PARITY_SPACE | Space.

anonymous enum

Flow control types.

Enumeration values:
COMM_FC_NONE | No flow control.
COMM_FC_XONXOFF_INPUT | XON/XOFF control of input data.
COMM_FC_XONXOFF_OUTPUT | XON/XOFF control of output data.
COMM_FC_RTSCTS_INPUT | RTS/CTS control of input data.
COMM_FC_RTSCTS_OUTPUT | RTS/CTS control of output data.
COMM_FC_DSRDTR_INPUT | DSR/DTR control of input data.
COMM_FC_DSRDTR_OUTPUT | DSR/DTR control of output data.

anonymous enum

Receive errors & special values.

Enumeration values:
COMM_ERROR_GENERAL | General error.
COMM_ERROR_OVERRUN | Overrun error.
COMM_ERROR_PARITY | Parity error.
COMM_ERROR_FRAMING | Framing error.
COMM_ERROR_TIMEOUT | Timeout expired.
COMM_STATE_CHANGED | State pins changed (CTS, DSR or RI). New bit values are specified in data field.

enum WaitResult

com_wait_for_data() function results.

Enumeration values:
COMM_WAIT_TIMEOUT | Timeout expired.
COMM_WAIT_DATAREADY | Data ready.
COMM_WAIT_ERROR | General error (e.g. port is absent).

enum com_dev_t

Available serial ports.

Enumeration values:
COMM_DEV_DEFAULT Default serial port.

Function Documentation

bool com_close ( com_t port )

Closes an opened serial port.

Parameters:
port the handle of a port to close.
Returns:
TRUE on success; FALSE otherwise
  #include <cybiko.h>
   ...
   com_t port;
   int data;
   ...
   // open the default serial port, wait a second for availability
   port = com_open( COMM_DEV_DEFAULT, 1000 );
   ...
   // read a byte, wait forever
   data = com_read( port, 0 );
   ...
   // close the port
   com_close( port );
   ...
See also:
com_open

bool com_flush ( com_t port )

Flushes serial port I/O buffers.

Parameters:
port the handle of a serial port.
Returns:
TRUE on success; FALSE otherwise

bool com_get_DTR ( com_t port )

Gets the serial port's current DTR state.

Parameters:
port the handle of a serial port.
Returns:
current DTR state

bool com_get_RTS ( com_t port )

Gets serial port's current RTS state.

Parameters:
port the handle of a serial port.
Returns:
current RTS state

bool com_get_config ( | com_t port,
 | struct COMMConfig * config )

Retrieves current configuration of a serial port.

Parameters:
port | the handle of a serial port.
config | COMMConfig structure that is to receive configuration data
Returns:
TRUE on success; FALSE otherwise

int com_get_state ( com_t port )

Retrieves current state of a serial port.

Parameters:
port the handle of a serial port.
Returns:
either of these constants: COMM_ERROR_* or COMM_STATE_CHANGED.

com_t com_open ( | com_dev_t device,
 | long timeout )

Opens a serial port for read / write access.

Parameters:
device | a port to open
timeout | the time to allow for the port to open, in milliseconds.
Returns:
the handle to an opened port, or 0 if the port is already opened.
  #include <cybiko.h>
   ...
   com_t port;
   int data;
   ...
   // open the default serial port, wait a second for availability
   port = com_open( COMM_DEV_DEFAULT, 1000 );
   ...
   // read a byte, wait forever
   data = com_read( port, 0 );
   ...
   // close the port
   com_close( port );
   ...
See also:
com_close

int com_read ( | com_t port,
 | long timeout )

Reads a byte from a serial port.

Parameters:
port | the handle of a port to read from
timeout | the time to allow for the byte to be read, in milliseconds.
Returns:
on success, the function returns non-negative value of the specified byte; on error, some negative value is returned. Though it can be only -1 for now, this may change in the future
  #include <cybiko.h>
   ...
   com_t port;
   int data;
   ...
   // open the default serial port, wait a second for availability
   port = com_open( COMM_DEV_DEFAULT, 1000 );
   ...
   // read a byte, wait forever
   data = com_read( port, 0 );
   ...
   // close the port
   com_close( port );
   ...
See also:
com_write

bool com_set_DTR ( | com_t port,
 | bool state )

Sets serial port's DTR state.

Parameters:
port | the handle of a serial port.
state | desired DTR state
Returns:
TRUE on success; FALSE otherwise

bool com_set_RTS ( | com_t port,
 | bool state )

Sets serial port's RTS state.

Parameters:
port | the handle of a serial port.
state | the desired RTS state.
Returns:
TRUE on success; FALSE otherwise.

bool com_set_config ( | com_t port,
 | struct COMMConfig * config )

Sets the serial port's configuration.

Parameters:
port | the handle of a serial port.
config | COMMConfig structure containing the configuration data.
Returns:
TRUE on success; FALSE otherwise.

int com_wait_for_data ( | com_t port,
 | long timeout )

Waits for data from a serial port.

Parameters:
port | the handle of the serial port in which to look in
timeout | the time to allow for the byte to read, in milliseconds.
Returns:
one of the WaitResult constants.

bool com_write ( | com_t port,
 | int value,
 | long timeout )

Writes a byte to a serial port.

Parameters:
port | the handle of the port to which the byte should be written.
value | the value of the byte to be written; low-order byte is used.
Returns:
TRUE on success; FALSE otherwise.
  #include <cybiko.h>
   ...
   static void my_com_print( com_t port, const char* str )
   {
     int i;
     for( i = 0; str[ i ]; i++ )
     {
       com_write( port, str[ i ], 0 );
     }
   }
   ...
See also:
com_read


COMMConfig Struct Reference

Public Attributes
char | baud_rate
char | data_bits
char | stop_bits
char | parity_type
char | flow_control
char | XON_char
char | XOFF_char
char | reserved
clock_t timeout

Detailed Description

See also:
Serial Port Access

Member Data Documentation

char XOFF_char

Character used as XOFF.

char XON_char

Character used as XON.

char baud_rate

Placeholder for COMM_BAUD_* values.

char data_bits

Placeholder for COMM_DATABITS_* values.

char flow_control

Placeholder for COMM_FC_* values.

char parity_type

Placeholder for COMM_PARITY_* values.

char reserved

Reserved.

char stop_bits

Placeholder for COMM_STOPBITS_* values.

clock_t timeout

Maximum timeout (in ms) between write() call and actual byte sending.


Formatted Output

Functions
void | TRACE (char *sz_format[, argument]...)
int | cprintf (char *sz_format[, argument]...)
int | sprintf (char *ptr_buffer, char *sz_format[, argument]...)
int | vsprintf (char *ptr_buffer, char *sz_format, va_list argv_list)

Detailed Description

With the help of these functions you can output data to either console or string buffer.

Function Documentation

void TRACE ( char *sz_format...[, argument] )

Traces to the system console.
Specifies a variable number of arguments that are used in exactly the same way that a variable number of arguments are used in the run-time function cprintf. Use format and variable arguments to format your message and make it readable and informative. Please keep in mind that it adds a Thread/timers prefix to the line, as well as necessary line ends.

Parameters:
sz_format | format control(see sprintf() for the full format description).
argument | optional arguments.
Returns:
none.
       #include <cybiko.h>
       ...
       TRACE( "Hello, World!" );
       ...
See also:
cprintf, sprintf.

int cprintf ( char *sz_format...[, argument] )

Formats and prints the string to the Cybiko console.

Parameters:
sz_format | format control(see sprintf() for the full format description).
argument | optional arguments.
Returns:
the number of characters printed.
       #include <cybiko.h>
       ...
       int nVal;
       nVal = 54;
       ...
       cprintf( "nVal = %d", nVal );
       ...
See also:
TRACE, sprintf.

int sprintf ( | char * ptr_buffer,
 | char *sz_format...[, argument] )

Writes formatted data to a string.
This function works almost exactly like standard C one, but it does not support all format tags and specifiers. If you've never heard about printf routines, here's the general idea: you specify a format line with some text that may contain format tags. For each format tag found, sprintf() takes a parameter for the stack. This method does not allow a compile time check, but it does give you enormous flexibility and effectiveness. So, you code it this way:

  sprintf( buffer_ptr, "My number is %-10d",123);
Here '-10d' is a format tag that says, "there is a decimal value to be printed with left justification in the 10 characters field."

The following format specifiers are allowed:

%[-][0][<size>][{l|L}]{i|d|x|X|s|c|%}

Their meaning is standard:

  • leading '-' sets left justification (the default is right)
  • if leading zero is specified, leading zeroes will be printed for numbers.
  • optional <size> (decimal number) sets the size of the output field
  • optional 'l' or 'L' prefix means that number is long
  • 'i' and 'd' causes a decimal integer to be printed
  • 'x' and 'X' causes a hexadecimal number (with small or capital letters, respectively) to be printed
  • 's' refers to a character string (might be UNICODE or bytes)
  • 'c' means single character
  • '%' means "just put out a percent character without taking arguments."
All other characters in the format line will be just printed out as is. Remember, it is up to you to handle the arguments list and the format line in the correct correspondence.
Parameters:
ptr_buffer | a storage location for output.
sz_format | format-control string. @argument optional arguments.
Returns:
the number of characters written, not including the terminating null character, or a negative value if an output error occurs.
       #include <cybiko.h>
       #define FIRST_PLAYER_WINS            0
       #define SECOND_PLAYER_WINS           1
       ...
       const char* sz_format = "%s player WINS!";
       const char* sz_player_name[2] = {
                                         "First",
                                         "Second"
                                       };
       int game_result;
       char sz_result_string[24];
       ...
       sprintf( sz_result_string, sz_format, sz_player_name[ game_result ] );
       ...

int vsprintf ( | char * ptr_buffer,
 | char * sz_format,
 | va_list argv_list )

Writes formatted output using a pointer to a list of arguments.

Parameters:
ptr_buffer | a storage location for output.
sz_format | format-control string(see sprintf() for the full format description).
argv_list | a pointer to a list of arguments.
Returns:
the number of characters written, not including the terminating null character, or a negative value if an output error occurs.
      #include <cybiko.h>
      ...
      //  Logs errors to the file.
      void trace2logfile(char* sz_format, ...)
      {
        va_list parameters;
        char sz_buffer[64];
        struct FileOutput* ptr_log_file;

        //  Formats string.
        va_start( parameters, sz_format );
        vsprintf( sz_buffer, sz_format, parameters );
        va_end( parameters );

        //  Writes it to file "error.log".
        ptr_log_file = (struct FileOutput*)malloc( sizeof( struct FileOutput ) );
        FileOutput_ctor_Ex( ptr_log_file, "error.log", TRUE );
        FileOutput_seekp( ptr_log_file, 0, SEEK_END );
        FileOutput_write( ptr_log_file, sz_buffer, strlen(sz_buffer) );
        FileOutput_dtor( ptr_log_file, FREE_MEMORY );
      }
      ...
See also:
va_start, va_end, va_arg.


String Manipulation

Functions
char* | strstr (char *sz_str_1, char *sz_str_2)
char* | strcpy (char *sz_destination, char *sz_source)
int | strncpy (char *sz_destination, char *sz_source, size_t count)
int | strcmp (char *sz_string_1, char *sz_string_2)
int | strncmp (char *string_1, char *string_2, size_t count)
char* | strchr (char *sz_source, char character)
char* | strrchr (char *sz_source, int character)
bool | strstarts (char *sz_source, char *sz_start_string)
bool | strends (char *sz_source, char *sz_tail_string)
bool | strmatch (char *sz_pattern, char *sz_source)
bool | is_pattern (char *sz_source)
char* | skipws (char *sz_source)
size_t | strlen (char *sz_source)
char* | strcat (char *sz_destination, char *sz_source)
char* | trunc_spaces (char *sz_text)

Detailed Description

Some functions for string manipulations. Among these functions you can find ANSI C compatible ones( like strcpy(), strcmp() and others) as well as and functions specific to CyOS (is_pattern(), trunc_spaces(), strends()).

Function Documentation

bool is_pattern ( char * sz_source )

Checks whether string contains '*' or '?' characters.

Parameters:
sz_source A source string
Returns:
TRUE if source string contains '*' or '?' characters, otherwise FALSE
       #include <cybiko.h>
       ...
       bool open_file( char* sz_name )
       {
         if( is_pattern( sz_name ) )
         {
           //  Searches file using pattern.
           ...
         }
         //  Opens file.
         ...
       }
       ...

char * skipws ( char * sz_source )

Skips white spaces.

Parameters:
sz_source A source string
Returns:
The source string without white spaces.
        #include <cywin.h>
        ...
        char test_string[ 20 ];
        ...
        strcpy( test_string, "Any string" );
        //  Outputs: Any string
        TRACE( "%s", test_string );
        //  Outputs: Anystring
        TRACE( "%s", skipws( test_string ) );

char * strcat ( | char * sz_destination,
 | char * sz_source )

Appends one string to another and terminates the resulting string with a null character.
The initial character of the source string overwrites the terminating null character of the destination string. No overflow checking is performed when strings are copied or appended. The behavior of strcat is undefined if the source and destination strings overlap.

Parameters:
sz_destination | A null-terminated destination string.
sz_source | A null-terminated source string.
Returns:
The destination string
       #include <cybiko.h>
       ...
       const char sz_name = "world";
       char sz_string[20];
       ...
       strcpy( sz_string, "Hello," );
       strcat( sz_string, sz_name );
       strcat( sz_string, "!" );
       ...
       //  Traces "Hello, world!".
       TRACE( "Result: %s", sz_string);
       ...

char * strchr ( | char * sz_source,
 | char character )

Finds a character in a string.

Parameters:
sz_source | A null-terminated source string
character | A character to be located
Returns:
A pointer to the first occurrence of a character in a string the source string, or NULL if a character is not found
       #include <cybiko.h>
       ...
       const char* sz_string = "I have 2 Cybiko computers!";
       char* ptr_amount;
       ...
       if( ( ptr_amount = strchr( sz_string, '2' ) ) )
       {
         *ptr_amount = '6';
       }
       //  Traces "I have 6 Cybiko computers!".
       TRACE( sz_string );
       ...

int strcmp ( | char * sz_string_1,
 | char * sz_string_2 )

Compares characters from two strings.

Parameters:
sz_string_1 | First null-terminated string to compare
sz_string_2 | Second null-terminated string to compare
Returns:
0 if sz_string_1 is identical to sz_string_2. Positive value if sz_string_1 is greater (in lexical meaning) than sz_string_2. Negative value if sz_string_1 is greater (in lexical meaning) than sz_string_2.
       #include <cybiko.h>
       ...
       char* string_1 = "AAAAAAAAAB";
       char* string_2 = "AAAAAAAAAA";
       ...
       if( !strcmp( string_1, string_2 ) )
       {
         //  Strings are not identical, because
         //  string_1 is greater then string_2 in lexical meaning.
         ...
       }
       ...
See also:
strncmp.

char * strcpy ( | char * sz_destination,
 | char * sz_source )

Copies a string, including the terminating null character to the destination buffer.
No overflow checking is performed when strings are copied or appended. The behavior of strcpy() is undefined if the source and destination strings overlap.

Parameters:
sz_destination | A destination buffer
sz_source | A null-terminated source string
Returns:
The destination string
       #include <cybiko.h>
       ...
       const char* sz_name = "world";
       char sz_string[20];
       ...
       strcpy( sz_string, "Hello," );
       strcat( sz_string, sz_name );
       strcat( sz_string, "!" );
       ...
       //  Traces "Hello, world!".
       TRACE( "Result: %s", sz_string);
       ...
See also:
strncpy.

bool strends ( | char * sz_source,
 | char * sz_tail_string )

Checks whether the string ends with a specified substring.

Parameters:
sz_source | A pointer to the null-terminated source string.
sz_tail_string | A pointer to the null-terminated string to be located at the end of the source string.
Returns:
TRUE if the source string ends with the specified string.
       #include <cybiko.h>
       ...
       const char* name_list[6] = {
                                    "Dave",
                                     "Steve",
                                    "Jane",
                                    "Bill",
                                    "Robin",
                                    "John"
                                  };
       int index;
       ...
       //  Traces:
       //          "Names ending with e:"
       //          "Dave"
       //          "Steve"
       //          "Jane"
       TRACE("Names ending with e:");
       for( index = 0; index < 6 ; index ++)
       {
         if( strends( name_list[index], "e" ) )
         {
           TRACE("%s", name_list[index]);
         }
       }
       ...
See also:
strstarts.

size_t strlen ( char * sz_source )

Returns the length of a string, not including the terminating null character.

Parameters:
sz_source A null-terminated source string
Returns:
The number of characters in the string
       #include <cybiko.h>
       ...
       char* sz_string;
       char* sz_source_string;
       ...
       sz_string = (char*)malloc( 10 );
       ...
       if( strlen( sz_source_string ) <= 10)
       {
         sz_string = (char*)realloc( sz_string,
                                     strlen( sz_source_string ) + 1 );
       }
       ...
       free(sz_string);
       ...

bool strmatch ( | char * sz_pattern,
 | char * sz_source )

Checks wildcard match of the string to the pattern.
This function calculates a fast recursive pattern match using character '*' to match any characters with values of zero or more, and '?' to match exactly any single character. All other characters require the exact same ones as the testing string. Since this function is recursive, it does stack checking to prevent uncaught stack overflow. Checks wildcard match of a string to a pattern.

Parameters:
sz_pattern | A pointer to the pattern to check match
sz_source | A pointer to the source string
Returns:
TRUE if the pattern matches the source string, otherwise FALSE.
       #include <cybiko.h>
       ...
       const char* name_list[6] = {
                                    "Dave",
                                    "Steve",
                                    "Jane",
                                    "Bill",
                                    "Robin",
                                    "John"
                                  };
       int index;
       ...
       //  Traces:
       //          "Names with the "?a*" pattern:"
       //          "Dave"
       //          "Jane"
       TRACE("Names with the \"?a*\" pattern:");
       for( index = 0; index < 6 ; index ++)
       {
         if( strmatch( "?a*", name_list[index] ) )
         {
           TRACE("%s", name_list[index]);
         }
       }
       ...

int strncmp ( | char * string_1,
 | char * string_2,
 | size_t count )

Compares characters from two strings.

Parameters:
sz_string_1 | First null-terminated string to compare
sz_string_2 | Second null-terminated string to compare
count | Number of characters to compare
Returns:
0 if sz_string_1 is identical to sz_string_2. Positive value if sz_string_1 is greater (in lexical meaning) than sz_string_2. Negative value if sz_string_1 is greater (in lexical meaning) than sz_string_2.
       char* string_1 = "AAAAAAAAAB";
       char* string_2 = "AAAAAAAAAA";
       ...
       if( strncmp( string_1, string_2, 6 ) )
       {
         //  Strings are identical, because we compare
         //  only the first 6 characters.
         ...
       }
       ...
See also:
strcmp.

int strncpy ( | char * sz_destination,
 | char * sz_source,
 | size_t count )

Copies the initial count characters of the source string to the destination buffer.
If the count is less than or equal to the length of the source string, only count - 1 characters are copied from the source string, and a null character is appended automatically to the copied string. If the count is greater than the length of the source string, the destination string is padded with null characters up to the length count. The behavior of strncpy is undefined if the source and destination strings overlap.

Parameters:
sz_destination | A destination buffer
sz_source | A null-terminated source string
count | Number of characters to be copied
Returns:
The destination string
       #include <cybiko.h>
       ...
       const char* sz_string = "My nickname is CyCat. I love Cybiko!";
       char sz_nicname[NICKNAMESIZE + 1];
       ...
       strncpy( sz_string + 15, sz_nicname, NICKNAMESIZE + 1);
       //  Traces "His nickname is CyCat".
       TRACE("His nickname is %s", sz_nicname);
       ...
See also:
strcpy.

char * strrchr ( | char * sz_source,
 | int character )

Scans a string for the last occurrence of a character.

Parameters:
sz_source | A pointer to a string.
character | A character to be located.
Returns:
A pointer to the last occurrence of character in string the source string, or NULL if character is not found.
       #include <cybiko.h>
       ...
       const char* sz_string = "I have 2 Cybikos! My friend Peter has 1 Cybiko.";
       char* ptr_amount;
       ...
       if( ( ptr_amount = strchr( sz_string, '1' ) ) )
       {
         *ptr_amount = '2';
       }
       //  Traces "I have 2 Cybikos! My friend Peter has 1 Cybiko.".
       TRACE( sz_string );
       ...

bool strstarts ( | char * sz_source,
 | char * sz_start_string )

Checks whether a string starts with a specified substring.

Parameters:
sz_source | A pointer to the null-terminated source string
sz_start_string | A pointer to the null-terminated string to be located at the beginning of the source string
Returns:
TRUE if the source string starts with the specified string
       #include <cybiko.h>
       ...
       const char* name_list[6] = {
                                    "Dave",
                                    "Steve",
                                    "Jane",
                                    "Bill",
                                    "Robin",
                                    "John"
                                  };
       int index;
       ...
       //  Traces:
       //          "Names beginning with J:"
       //          "Jane"
       //          "John"
       TRACE("Names beginning with J:");
       for( index = 0; index < 6 ; index ++)
       {
         if( strstarts( name_list[index], "J" ) )
         {
           TRACE("%s", name_list[index]);
         }
       }
       ...
See also:
strends.

char * strstr ( | char * sz_str_1,
 | char * sz_str_2 )

Finds a substring.

Parameters:
sz_str_1 | A null-terminated string to search
sz_str_2 | A null-terminated string to search for
Returns:
A pointer to the first occurrence of sz_str_2 in sz_str_1
       #include <cybiko.h>
       ...
       char* sz_first_occurrence;
       char* sz_string = "The old string !";
       ...
       if( ( sz_first_occurrence = strstr( string, "old" ) ) )
       {
         memcpy( sz_first_occurrence, "new", 3 );
       }
       //  Traces "The new string !".
       TRACE( "Result: %s", sz_string );
       ...

char * trunc_spaces ( char * sz_text )

Removes spaces from the string.

Parameters:
sz_text String to be modified
Returns:
A pointer to the string without spaces
        #include <cywin.h>
        ...
        char test_string[ 20 ];
        ...
        strcpy( test_string, "Any string" );
        //  Outputs: Any string
        TRACE( "%s", test_string );
        //  Outputs: Anystring
        TRACE( "%s", trunc_spaces( test_string ) );


Conversion Routines

Functions
void | cyid2str (char *sz_cy_id, cyid_t cy_id)
cyid_t | str2cyid (char *sz_cy_id)
long | atoul (char *sz_source)
long | xtoi (char *sz_source)
long | htoul (char *sz_source)

Detailed Description

These functions are used to convert values from one format to another. Please make special note of cyid2str() and str2cyid(), because they can help to convert CyID to string and vice versa.

Function Documentation

long atoul ( char * sz_source )

Converts ASCII decimal into long.

Parameters:
sz_source a string to be converted.
Returns:
long value produced by interpreting the input characters as a number.
       #include <cywin.h>
       ...
       long amount;
       struct cDialog dialog;
       struct module_t main_module;
       char sz_amount[11];
       ...
       init_module( &main_module );
       ...
       cDialog_ctor( &dialog,
                     "Apples",
                     "Enter amount:",
                     mbOk | mbCancel | mbEdit,
                     10,
                     main_module.m_process );
       if( cDialog_ShowModal( &dialog ) == mrOk )
       {
         cDialog_GetEditText( &dialog, sz_amount );
       }
       cDialog_dtor( &dialog, LEAVE_MEMORY );
       amount = atoul( sz_amount );
       ...

void cyid2str ( | char * sz_cy_id,
 | cyid_t cy_id )

Converts CyID from cyid_t to text.

Parameters:
sz_cy_id | buffer for the CyID in text form.
cy_id | CyID to convert.
Returns:
None
       #include <cybiko.h>
       ...
       char sz_str_ID[10];
       cyid_t current_device_id = 0;
       ...
       TRACE( "Devices around:" );
       while( current_device_id = get_people_around( current_device_id ) )
       {
         cyid2str( sz_str_ID, current_device_id );
         TRACE( "%s", sz_str_ID );
       }
       ...
See also:
str2cyid.

long htoul ( char * sz_source )

Converts hexadecimal ASCII into long.

Parameters:
sz_source a string to be converted.
Returns:
long value produced by interpreting the input characters as a hexadecimal value.
       #include <cywin.h>
       ...
       long device_id;
       struct cDialog dialog;
       struct module_t main_module;
       char sz_device_id[11];
       ...
       init_module( &main_module );
       ...
       cDialog_ctor( &dialog,
                     "Connection property",
                     "Enter device id (in hexadecimal form):",
                     mbOk | mbCancel | mbEdit,
                     10,
                     main_module.m_process );
       if( cDialog_ShowModal( &dialog ) == mrOk )
       {
         cDialog_GetEditText( &dialog, sz_device_id );
       }
       cDialog_dtor( &dialog, LEAVE_MEMORY );
       device_id = htoul( sz_device_id );
       ...

cyid_t str2cyid ( char * sz_cy_id )

Converts CyID from text form to cyid_t.

Parameters:
sz_cy_id CyID in text form.
Returns:
CyID in cyid_t form.
       #include <cybiko.h>
       #define MSG_CLIENT_PING    MSG_USER + 1
       ...
       struct Message* ptr_message;
       char sz_game_server_ID[10];
       ...
       //  Obtains sz_game_server_ID.
       ...
       ptr_message = Message_new( sizeof( struct Message ) );
       ptr_message->msgid = MSG_CLIENT_PING;
       Message_post(ptr_message, "game_server", str2cyid( sz_partner_ID ) );
       ...
See also:
cyid2str.

long xtoi ( char * sz_source )

Converts some ASCII number into long.
First, this function skips white spaces (including the spaces at the ends of lines), then tries to detect the base by checking the beginning of the number. It understands these hexadecimal prefixes: 'x<hex-val> 0x<hex-val> H'<hex-val> h'<hex-val> -<dec-val> <dec-val>' where hex-val is some set of hexadecimal digits (0123456789ABCDEFabcdef), val - decimal value.

Parameters:
sz_source a string to be converted.
Returns:
long value produced by interpreting the input characters as a number.
       #include <cywin.h>
       ...
       long device_id;
       struct cDialog dialog;
       struct module_t main_module;
       char sz_device_id[11];
       ...
       init_module( &main_module );
       ...
       cDialog_ctor( &dialog,
                     "Connection property",
                     "Enter device id:",
                     mbOk | mbCancel | mbEdit,
                     10,
                     main_module.m_process );
       if( cDialog_ShowModal( &dialog ) == mrOk )
       {
         cDialog_GetEditText( &dialog, sz_device_id );
       }
       cDialog_dtor( &dialog, LEAVE_MEMORY );
       device_id = xtoi( sz_device_id );
       ...


Integer Math

Functions
long | random (int max)
void | srand (int seed)
int | imin (int first_value, int second_value)
int | imax (int first_value,int second_value)

Compounds
struct bitset Works with a set of bits using simple bit operations

Detailed Description

Here you can find some mathematical functions, imin() and imax() among them. If you need to find the minimal or maximal of two numbers, look at these efficient functions.

Function Documentation

int imax ( | int first_value,
 | int second_value )

Returns the maximum of the two values.

Parameters:
first_value | first value to be compared.
second_value | second value to be compared.
Returns:
The maximum of the two values
        #include <cywin.h>
        ...
        struct rect_t object_1;
        struct rect_t object_2;
        struct rect_t rect_and;
        ...
        //  Obtains intersection of two rectangles.
        rect_and.x = imax( object_1.x, object_2.x );
        rect_and.y = imax( object_1.y, object_2.y );
        rect_and.w = imin( object_1.x + object_1.w,
                           object_2.x + object_2.w) - rect_and.x;
        rect_and.h = imin( object_1.y + object_1.h,
                           object_2.y + object_2.h) - rect_and.y;
        ...
See also:
imin.

int imin ( | int first_value,
 | int second_value )

Returns the minimum of the two values.

Parameters:
first_value | first value to be compared.
second_value | second value to be compared.
Returns:
The minimum of the two values.
        #include <cywin.h>
        ...
        struct rect_t object_1;
        struct rect_t object_2;
        struct rect_t rect_and;
        ...
        //  Obtains intersection of two rectangles.
        rect_and.x = imax( object_1.x, object_2.x );
        rect_and.y = imax( object_1.y, object_2.y );
        rect_and.w = imin( object_1.x + object_1.w,
                           object_2.x + object_2.w ) - rect_and.x;
        rect_and.h = imin( object_1.y + object_1.h,
                           object_2.y + object_2.h ) - rect_and.y;
        ...
See also:
imax.

long random ( int max )

Returns a pseudo-random value from 0 to max - 1.

Parameters:
max the value what determines the range of return values. This range is [0, max-1].
Returns:
A pseudo-random value from 0 to max-1.
       #include <cybiko.h>
       ...
       int nRandVal;
       ...
       //  Returns pseudo-random value from 0 to 99.
       nRandVal = random( 100 );

void srand ( int seed )

Initializes a pseudo-random number generator.

Parameters:
seed Seed for pseudo-random number generation
Returns:
None.
       #include <cybiko.h>
       ...
       int nValue;
       ...
       srand( clock() );
       ...
       nValue = random( 100 );
       ...


bitset Struct Reference

Public Methods
struct bitset* | bitset_ctor (struct bitset *ptr_bitset, short size)
void | bitset_clear (struct bitset *ptr_bitset)
void | bitset_excl (struct bitset *ptr_bitset, short fbit)
bool | bitset_in (struct bitset *ptr_bitset, short fbit)
void | bitset_incl (struct bitset *ptr_bitset, short fbit)
void | bitset_add (struct bitset *ptr_bitset_1, struct bitset *ptr_bitset_2)
void | bitset_mul (struct bitset *ptr_bitset_1, struct bitset *ptr_bitset_2)
void | bitset_sub (struct bitset *ptr_bitset_1, struct bitset *ptr_bitset_2)
void | bitset_dtor (struct bitset *ptr_bitset, int memory_flag)

Detailed Description

Works with a set of bits using simple bit operations.

You must call the bitset_ctor() function before use, and the bitset_dtor() function after use.

See also:
Integer Math

Member Function Documentation

void bitset_add ( | struct bitset * ptr_bitset_1,
 | struct bitset * ptr_bitset_2 )

Adds two bitsets, the same as logical OR.
The result will be stored in the first bitset.

Parameters:
ptr_bitset_1 | A pointer to the first bitset
ptr_bitset_2 | A pointer to the second bitset
Returns:
None
       #include <cybiko.h>
       ...
       struct bitset btset1;
       struct bitset btset2;
       bitset_ctor( &btset1, 8 );
       bitset_ctor( &btset2, 8 );
       ...
       bitset_clear( &btset1 );
       bitset_clear( &btset2 );

       bitset_incl( &btset1 , 0 );
       bitset_incl( &btset1 , 1 );
       bitset_incl( &btset2 , 0 );
       bitset_incl( &btset2 , 2 );
       ...
       //  Performs the logical OR operation.
       //  Before call:
       //      btset1   00000011
       //      btset2   00000101
       //  After call:
       //      btset1   00000111
       //      btset2   00000101
       bitset_add( &btset1, &btset2 );
       ...
       bitset_dtor( &btset1, LEAVE_MEMORY );
       bitset_dtor( &btset2, LEAVE_MEMORY );

void bitset_clear ( struct bitset * ptr_bitset )

Sets all bits to zero.

Parameters:
ptr_bitset A pointer to the initialized bitset object
Returns:
None
       #include <cybiko.h>
       ...
       struct bitset float_value;
       bitset_ctor( &float_value, 32 );
       ...
       //  Sets a value to zero.
       bitset_clear( &float_value );
       ...
       bitset_dtor( &float_value, LEAVE_MEMORY );

struct bitset * bitset_ctor ( | struct bitset * ptr_bitset,
 | short size )

Creates a set of bits.

Parameters:
ptr_bitset | A pointer to a bitset object
size | The number of bits in a bitset object
Returns:
A pointer to the initialized bitset object
       #include <cybiko.h>
       #define SIGN_BIT    31
       ...
       struct bitset float_value;
       bitset_ctor( &float_value, 32 );
       ...
       //  Takes abs of a value.
       bitset_excl( &float_value, SIGN_BIT );
       ...
       bitset_dtor( &float_value, LEAVE_MEMORY );
See also:
bitset_dtor.

void bitset_dtor ( | struct bitset * ptr_bitset,
 | int memory_flag )

The bitset destructor.
Deletes a bitset object.

Parameters:
ptr_bitset | A pointer to the initialized bitset object.
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in stack
Returns:
None
       #include <cybiko.h>
       #define SIGN_BIT    31
       ...
       struct bitset float_value;
       bitset_ctor( &float_value, 32 );
       ...
       //  Takes abs of a value.
       bitset_excl( &float_value, SIGN_BIT );
       ...
       bitset_dtor( &float_value, LEAVE_MEMORY );
See also:
bitset_ctor, FREE_MEMORY, LEAVE_MEMORY.

void bitset_excl ( | struct bitset * ptr_bitset,
 | short fbit )

Excludes a bit from the set at a specified position.

Parameters:
ptr_bitset | A pointer to the initialized bitset object
fbit | The position of the bit to exclude
Returns:
None
       #include <cybiko.h>
       #define SIGN_BIT    31
       ...
       struct bitset float_value;
       bitset_ctor( &float_value, 32 );
       ...
       //  Takes abs of a value.
       bitset_excl( &float_value, SIGN_BIT );
       ...
       bitset_dtor( &float_value, LEAVE_MEMORY );
See also:
bitset_in, bitset_incl.

bool bitset_in ( | struct bitset * ptr_bitset,
 | short fbit )

Determines whether the bit at a specified position was excluded.

Parameters:
ptr_bitset | A pointer to the initialized bitset object.
fbit | The position of the bit to test
Returns:
TRUE if the bit at the specified position was not excluded
       #include <cybiko.h>
       #define SIGN_BIT    31
       ...
       {
         struct bitset float_value;
         bitset_ctor( &float_value, 32 );
         ...
         //  Inverses a value.
         if( bitset_in( &float_value, SIGN_BIT ) )
         {
           bitset_excl( &float_value, SIGN_BIT );
         }
         else
         {
           bitset_incl( &float_value, SIGN_BIT );
         }
         ...
         bitset_dtor( &float_value, LEAVE_MEMORY );
       }
See also:
bitset_excl, bitset_incl.

void bitset_incl ( | struct bitset * ptr_bitset,
 | short fbit )

Adds the bit at a specified position to the set.

Parameters:
ptr_bitset | A pointer to the initialized bitset object
fbit | The position of the bit to test
Returns:
None
       #include <cybiko.h>
       #define SIGN_BIT    31
       ...
       {
         struct bitset float_value;
         bitset_ctor( &float_value, 32 );
         ...
         //  Inverses a value.
         if( bitset_in( &float_value, SIGN_BIT ) )
         {
           bitset_excl( &float_value, SIGN_BIT );
         }
         else
         {
           bitset_incl( &float_value, SIGN_BIT );
         }
         ...
         bitset_dtor( &float_value, LEAVE_MEMORY );
       }
See also:
bitset_excl, bitset_in.

void bitset_mul ( | struct bitset * ptr_bitset_1,
 | struct bitset * ptr_bitset_2 )

Multiplies two bitsets, the same as logical AND.
The result will be stored in the first bitset.

Parameters:
ptr_bitset_1 | A pointer to the first bitset
ptr_bitset_2 | A pointer to the second bitset
Returns:
None
       #include <cybiko.h>
       ...
       struct bitset btset1;
       struct bitset btset2;
       bitset_ctor( &btset1, 8 );
       bitset_ctor( &btset2, 8 );
       ...
       bitset_clear( &btset1 );
       bitset_clear( &btset2 );

       bitset_incl( &btset1 , 0 );
       bitset_incl( &btset1 , 1 );
       bitset_incl( &btset2 , 0 );
       bitset_incl( &btset2 , 2 );
       ...
       //  Performs the logical AND operation.
       //  Before call:
       //      btset1   00000011
       //      btset2   00000101
       //  After call:
       //      btset1   00000001
       //      btset2   00000101
       bitset_mul( &btset1, &btset2 );
       ...
       bitset_dtor( &btset1, LEAVE_MEMORY );
       bitset_dtor( &btset2, LEAVE_MEMORY );

void bitset_sub ( | struct bitset * ptr_bitset_1,
 | struct bitset * ptr_bitset_2 )

Subtracts two bitsets, the same as logical XOR.
The result will be stored in the first bitset.

Parameters:
ptr_bitset_1 | A pointer to the first bitset.
ptr_bitset_2 | A pointer to the second bitset.
Returns:
None
       #include <cybiko.h>
       ...
       struct bitset btset1;
       struct bitset btset2;
       bitset_ctor( &btset1, 8 );
       bitset_ctor( &btset2, 8 );
       ...
       bitset_clear( &btset1 );
       bitset_clear( &btset2 );

       bitset_incl( &btset1 , 0 );
       bitset_incl( &btset1 , 1 );
       bitset_incl( &btset2 , 0 );
       bitset_incl( &btset2 , 2 );
       ...
       //  Performs the logical XOR operation.
       //  Before call:
       //      btset1   00000011
       //      btset2   00000101
       //  After call:
       //      btset1   00000110
       //      btset2   00000101
       bitset_sub( &btset1, &btset2 );
       ...
       bitset_dtor( &btset1, LEAVE_MEMORY );
       bitset_dtor( &btset2, LEAVE_MEMORY );


Vararg Functions

Typedefs
typedef char* | va_list

Functions
void | va_start (va_list ptr_arg, prev_param)
type | va_arg (va_list ptr_arg, type)
void | va_end (va_list ptr_arg)

Detailed Description

Some functions for handling variable numbers of arguments (like those in stdarg.h).

Typedef Documentation

typedef char * va_list

Storage to hold information needed by the va_start(), va_arg() and va_end() macros.
The called function declares a variable of type va_list that can be passed as an argument to another function.

See also:
va_start, va_end, va_arg.

Function Documentation

type va_arg ( | va_list ptr_arg,
 | type )

Retrieves the current argument from the list of optional arguments for variable argument function.

Parameters:
ptr_arg | A pointer to the list of arguments
type | Type of the argument to retrieve
Returns:
Current argument from the list of optional arguments
      #include <cybiko.h>
      ...
      //  Traces strings.
      void trace_multistring(int string_number, ...)
      {
        int index;
        va_list parameters;
        va_start( parameters, string_number );
        for( index = 0; index < string_number; index ++ )
        {
          TRACE( va_arg( parameters, char* ) );
        }
        va_end( parameters );
      }
      ...
      trace_multistring( 4, "One", "Two", "Three", "Four");
      ...
See also:
va_start, va_end.

void va_end ( va_list ptr_arg )

Releases a list of optional arguments for variable argument function.

Parameters:
ptr_arg A pointer to a list of arguments
Returns:
None
      #include <cybiko.h>
      ...
      //  Logs errors to the file.
      void trace2logfile(char* sz_format, ...)
      {
        va_list parameters;
        char sz_buffer[64];
        struct FileOutput* ptr_log_file;
        //  Formats string.
        va_start( parameters, sz_format );
        vsprintf( sz_buffer, sz_format, parameters );
        va_end( parameters );
        //  Writes it to file "error.log".
        ptr_log_file = (struct FileOutput*)malloc( sizeof( struct FileOutput ) );
        FileOutput_ctor_Ex( ptr_log_file, "error.log", TRUE );
        FileOutput_seekp( ptr_log_file, 0, SEEK_END );
        FileOutput_write( ptr_log_file, sz_buffer, strlen(sz_buffer) );
        FileOutput_dtor( ptr_log_file, FREE_MEMORY );
      }
      ...
See also:
va_start, va_arg.

void va_start ( | va_list ptr_arg,
 | prev_param )

Initializes a list of optional arguments for variable argument function.

Parameters:
ptr_arg | A pointer to list of arguments
prev_param | The parameter that precedes the first optional argument
Returns:
None
      #include <cybiko.h>
      ...
      //  Logs errors to the file.
      void trace2logfile(char* sz_format, ...)
      {
        va_list parameters;
        char sz_buffer[64];
        struct FileOutput* ptr_log_file;
        //  Formats string.
        va_start( parameters, sz_format );
        vsprintf( sz_buffer, sz_format, parameters );
        va_end( parameters );
        //  Writes it to file "error.log".
        ptr_log_file = (struct FileOutput*)malloc( sizeof( struct FileOutput ) );
        FileOutput_ctor_Ex( ptr_log_file, "error.log", TRUE );
        FileOutput_seekp( ptr_log_file, 0, SEEK_END );
        FileOutput_write( ptr_log_file, sz_buffer, strlen(sz_buffer) );
        FileOutput_dtor( ptr_log_file, FREE_MEMORY );
      }
      ...
See also:
va_end, va_arg.


Miscellaneous

Typedefs
typedef int | size_t

Functions
long | get_hardware_version (void)

Compounds
struct | Score | The game's high score archive
struct | score_t | The game's high score structure

Detailed Description

Structures and functions that don't fit anywhere else. By using Score structure methods, you make your game players' results available for upload to the Cybiko site. Thus, your game becomes contest-enabled!

Typedef Documentation

typedef int size_t

Result of the sizeof operator.

Function Documentation

long get_hardware_version ( void )

Returns the version of CYBIKO hardware.

Returns:
version of CYBIKO hardware.
       #include <cybiko.h>
       ...
       TRACE("Your hardware version is %ld", get_hardware_version() );
       ...


Score Struct Reference

Public Methods
struct Score* | Score_ctor (struct Score *ptr_score, struct Module *ptr_module)
void | Score_dtor (struct Score *ptr_score, int memory_flag)
bool | Score_is_valid (struct Score *ptr_score)
int | Score_get_record_count (struct Score *ptr_score)
bool | Score_read (struct Score *ptr_score, int index, struct score_t *ptr_result)
bool | Score_write (struct Score *ptr_score, int index, struct score_t *ptr_result)
bool | Score_write_Ex (struct Score *ptr_score, int index, long score, char *sz_nickname, cyid_t cyid, time_t time)

Detailed Description

The game's high score archive.

See also:
score_t, Miscellaneous

Member Function Documentation

struct Score * Score_ctor ( | struct Score * ptr_score,
 | struct Module * ptr_module )

High score archive constructor.
Before using this object, you must add an uncompressed "score.inf" file to the application archive. Specify its size as (number of records)*20 bytes. To disable file compression, use "-" before "score.inf" in the filer's file list.

Parameters:
ptr_score | A pointer to the high score archive structure
ptr_module | A pointer to the application's thread module
Returns:
A pointer to the initialized high score archive object
       #include <cybiko.h>
       ...
       int index;
       int record_number;
       struct module_t main_module;
       struct Score score_archive;
       struct score_t* high_scores;
       ...
       init_module( &main_module );
       ...
       Score_ctor( &score_archive, main_module.m_process->module );
       if( Score_is_valid ( &score_archive ) )
       {
         record_number = Score_get_record_count( &score_archive );
         high_scores = (struct score_t*)malloc( sizeof(struct score_t)*record_number );
         for( index = 0; index < record_number; index ++ )
         {
           Score_read( &score_archive, index, high_scores + index );
         }
         //  Changes high_scores.
         ...
         for( index = 0; index < record_number; index ++ )
         {
           Score_write( &score_archive, index, high_scores + index );
         }
         ...
         free(high_scores);
       }
       ...
       Score_dtor( &score_archive, LEAVE_MEMORY );
       ...

void Score_dtor ( | struct Score * ptr_score,
 | int memory_flag )

High score archive destructor.

Parameters:
ptr_score | A pointer to the initialized high score archive object.
memory_flag | Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None
       #include <cybiko.h>
       ...
       int index;
       int record_number;
       struct module_t main_module;
       struct Score score_archive;
       struct score_t* high_scores;
       ...
       init_module( &main_module );
       ...
       Score_ctor( &score_archive, main_module.m_process->module );
       if( Score_is_valid ( &score_archive ) )
       {
         record_number = Score_get_record_count( &score_archive );
         high_scores = (struct score_t*)malloc( sizeof(struct score_t)*record_number );
         for( index = 0; index < record_number; index ++ )
         {
           Score_read( &score_archive, index, high_scores + index );
         }
         //  Changes high_scores.
         ...
         for( index = 0; index < record_number; index ++ )
         {
           Score_write( &score_archive, index, high_scores + index );
         }
         ...
         free(high_scores);
       }
       ...
       Score_dtor( &score_archive, LEAVE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int Score_get_record_count ( struct Score * ptr_score )

Returns the number of records in the high score archive.

Parameters:
ptr_score A pointer to the initialized high score archive object
Returns:
Number of records in the high score archive
       #include <cybiko.h>
       ...
       int index;
       int record_number;
       struct module_t main_module;
       struct Score score_archive;
       struct score_t* high_scores;
       ...
       init_module( &main_module );
       ...
       Score_ctor( &score_archive, main_module.m_process->module );
       if( Score_is_valid ( &score_archive ) )
       {
         record_number = Score_get_record_count( &score_archive );
         high_scores = (struct score_t*)malloc( sizeof(struct score_t)*record_number );
         for( index = 0; index < record_number; index ++ )
         {
           Score_read( &score_archive, index, high_scores + index );
         }
         //  Changes high_scores.
         ...
         for( index = 0; index < record_number; index ++ )
         {
           Score_write( &score_archive, index, high_scores + index );
         }
         ...
         free(high_scores);
       }
       ...
       Score_dtor( &score_archive, LEAVE_MEMORY );
       ...

bool Score_is_valid ( struct Score * ptr_score )

Checks the validity of the high score archive.

Parameters:
ptr_score A pointer to the initialized high score archive object
Returns:
TRUE if the high score archive is valid, otherwise FALSE
       #include <cybiko.h>
       ...
       int index;
       int record_number;
       struct module_t main_module;
       struct Score score_archive;
       struct score_t* high_scores;
       ...
       init_module( &main_module );
       ...
       Score_ctor( &score_archive, main_module.m_process->module );
       if( Score_is_valid ( &score_archive ) )
       {
         record_number = Score_get_record_count( &score_archive );
         high_scores = (struct score_t*)malloc( sizeof(struct score_t)*record_number );
         for( index = 0; index < record_number; index ++ )
         {
           Score_read( &score_archive, index, high_scores + index );
         }
         //  Changes high_scores.
         ...
         for( index = 0; index < record_number; index ++ )
         {
           Score_write( &score_archive, index, high_scores + index );
         }
         ...
         free(high_scores);
       }
       ...
       Score_dtor( &score_archive, LEAVE_MEMORY );
       ...

bool Score_read ( | struct Score * ptr_score,
 | int index,
 | struct score_t * ptr_result )

Reads the record from the high score archive.

Parameters:
ptr_score | A pointer to the initialized high score archive object
index | The index of the record in the high score archive
ptr_result | A pointer to the buffer that receives the score
Returns:
TRUE if the record was read successfully
       #include <cybiko.h>
       ...
       int index;
       int record_number;
       struct module_t main_module;
       struct Score score_archive;
       struct score_t* high_scores;
       ...
       init_module( &main_module );
       ...
       Score_ctor( &score_archive, main_module.m_process->module );
       if( Score_is_valid ( &score_archive ) )
       {
         record_number = Score_get_record_count( &score_archive );
         high_scores = (struct score_t*)malloc( sizeof(struct score_t)*record_number );
         for( index = 0; index < record_number; index ++ )
         {
           Score_read( &score_archive, index, high_scores + index );
         }
         //  Changes high_scores.
         ...
         for( index = 0; index < record_number; index ++ )
         {
           Score_write( &score_archive, index, high_scores + index );
         }
         ...
         free(high_scores);
       }
       ...
       Score_dtor( &score_archive, LEAVE_MEMORY );
       ...
See also:
score_t.

bool Score_write ( | struct Score * ptr_score,
 | int index,
 | struct score_t * ptr_result )

Writes the record to the high score archive.

Parameters:
ptr_score | Pointer to the initialized high score archive object
index | Index of the record in the high score archive
ptr_result | A pointer to the game's high score structure
Returns:
TRUE if the record was stored successfully
       #include <cybiko.h>
       ...
       int index;
       int record_number;
       struct module_t main_module;
       struct Score score_archive;
       struct score_t* high_scores;
       ...
       init_module( &main_module );
       ...
       Score_ctor( &score_archive, main_module.m_process->module );
       if( Score_is_valid ( &score_archive ) )
       {
         record_number = Score_get_record_count( &score_archive );
         high_scores = (struct score_t*)malloc( sizeof(struct score_t)*record_number );
         for( index = 0; index < record_number; index ++ )
         {
           Score_read( &score_archive, index, high_scores + index );
         }
         //  Changes high_scores.
         ...
         for( index = 0; index < record_number; index ++ )
         {
           Score_write( &score_archive, index, high_scores + index );
         }
         ...
         free(high_scores);
       }
       ...
       Score_dtor( &score_archive, LEAVE_MEMORY );
       ...
See also:
Score_write_Ex, score_t.

bool Score_write_Ex ( | struct Score * ptr_score,
 | int index,
 | long score,
 | char * sz_nickname,
 | cyid_t cyid,
 | time_t time )

Writes the record to the high score archive.

Parameters:
ptr_score | A pointer to the initialized high score archive object
index | The index of the record in the high score archive
score | The high score value
sz_nickname | The Cy name of the player, who has reached the high score
cyid | The Cy ID of the device on which the score was reached
time | Time the high score was reached
Returns:
TRUE if the record was stored successfully.
       #include <cybiko.h>
       ...
       int index;
       int record_number;
       struct module_t main_module;
       struct Score score_archive;
       struct score_t* high_scores;
       ...
       init_module( &main_module );
       ...
       Score_ctor( &score_archive, main_module.m_process->module );
       if( Score_is_valid ( &score_archive ) )
       {
         record_number = Score_get_record_count( &score_archive );
         high_scores = (struct score_t*)malloc( sizeof(struct score_t)*record_number );
         for( index = 0; index < record_number; index ++ )
         {
           Score_read( &score_archive, index, high_scores + index );
         }
         //  Changes high_scores.
         ...
         for( index = 0; index < record_number; index ++ )
         {
           Score_write_Ex( &score_archive,
                           index,
                           high_scores[index].score,
                           high_scores[index].nickname,
                           high_scores[index].cyid,
                           high_scores[index].time );
         }
         ...
         free(high_scores);
       }
       ...
       Score_dtor( &score_archive, LEAVE_MEMORY );
       ...
See also:
Score_write, score_t.


score_t Struct Reference

Public Attributes
long | score
cyid_t cyid
time_t time
char | nickname [8]

Detailed Description

Structure of the high score of the game.

See also:
Score, Miscellaneous

Member Data Documentation

cyid_t cyid

Cy ID of the device on which the score was reached.

char nickname[8]

Cy name of the player, who reach the high score.

long score

High score.

time_t time

Time the high score was reached.


Overview API

API Description

CyOS is a full multitasking operational system. CyOS main features:
  • Preemptive multitasking
  • Memory management system
  • Graphics system
  • File system
  • Dynamic module loading
  • Dynamic linking
  • Means of interdevice communication
The 1.2.50 CyOS version functionally represents a multitask environment with an interprocess interaction. It includes peripherals access, a file system, a graphics support, sound, dynamic loaded units, applications archives, and means of information transmission via radio channels.

CyOS handles a task comprising one or several threads, or processes executed in pseudo-parallel as in displaced multitasking. The synchronization of threads is carried out by Mutex, Flag, and Flagex. A thread can be in the process of fulfillment, or queuing for fulfillment, or hibernating ahead of an event as in a timer.

The sending of messages addressed to processes on other devices represents the network exchange. The transmission is carried out through a radio channel with automatic assembly/disassembly of packages and a notice of delivery.

Application tasks are located on a file device as archives comprising several files. An archive includes a module under execution, resources files, and application description files in the oblate sort. When an application is started from the archive, the system extracts and unpacks the module under execution in its memory.

The application usually creates an object of the main process, bans outloading of the module from the memory, and returns the control to OS. After the initialization of an internal state, the created process transfers to the expectation of messages. The processor time is not spent on it. When a message arrives, the process revives, processes the message, and returns to the expectation mode.

Dynamic linking allows storing of frequently used components in separate executable modules, thus saves both long-storing device memory and RAM. CYBIKO gives a standard set of such modules.

System Pack is a set of standard interface modules and dynamic libraries. The main goal of System Pack is to provide uniform user interface in all applications.

There are currently seven libraries in the System Pack: Settings, Locales, Finder, Servers, Power Saver, CyWin, and Custom Dialogs. These libraries are intended to help programming in such features as communication with people, running applications, storage of various configuration data, handling different locales, management of system power, and graphics user interface.

All important system configuration settings are contained in specially organized storage. You can easily access or change these settings through the Settings library. If you need to display the current time for the user, you can take advantage of the Locales library because time is different for different countries. Using the Finder, you can determine how many people are currently around you and find out their nicknames and other data through a few function calls. Almost every application requires various data windows such as dialog boxes, forms, menus, and lists to display information to the user in a suitable form. The CyWin library can help you solve these tasks.

Service applications included in the System Pack provide a basic set of necessary user functions. They allow easy graphical management of programs on your Cybiko, store information about you and your friends, search for people, configure systems, and so on.


Overview Standards

Interface Standards

Cybiko, Inc. has prepared more than 200 service applications and games for release. These applications help attain a wide range of purposes, but they have uniform principles of user interface construction. Therefore, the menu, the lists, and the dialog box look and function identically in all applications. This is important, and it averts numerous problems. The developer might have the problem of debugging the applications, and the user might face the clarity problem.

This section contains recommendations for developing your own Cybiko applications. By adhering to these recommendations, you will follow the principles of forming the applications interface which the Cybiko, Inc. programmers use. This section is broken into subsections. The largest subsection comprises a set of pages describing dialog box types. It is called "Dialogs Views". You will find recommendations on choosing a level of the game, its beginning, interruption, and completion, as well as the initial conditions. You will find the rules concerning applications titles and the handling of sound in separate pages. More rules are assembled in the "Miscellaneous" section. Note that the interface standards are still in the development stage and they are being supplemented. If you have a question, analyze the application interfaces on your Cybiko or the interfaces which you can download from www.cybiko.com. You can also seek help in our technical support department.


PicView

Using the PicView program you can:

  1. Send pictures from your computer: change them into picture files, and put them on your Cybiko computer!
  2. Take your Cybiko pictures, stick them on your PC, and have some more fun with them!

Converter is a PC application that can be run at CyberLoad application by the button. Converter allows you to:

  1. Convert bitmaps files (*.bmp) to Cybiko picture files (*.pic) or (*.xpic), and to send pictures to Cybiko computer.
  2. Get Cybiko picture files (*.pic) or (*.xpic) to PC and convert to bitmap files (*.bmp).
  3. Convert midi files (*.mid) to Cybiko music files (*.music), and to send music files to Cybiko computer.

Converter consists of:

  1. Converter main window;
  2. Picture Adjustment Box;
  3. Cybiko Picture to PC Bitmap Converter Box;
  4. Music File Converter Box.