=========================
Implementation and Usage
=========================

.. index::
	pair: Implementation and Usage; Download and Implementation

Download and Implementation
============================

To use this extension you have to start with downloading it following next steps:

1. Download the extension from `GitHub <https://github.com/MajdiSobain/ring_wincreg/releases>`_ or `Sourceforge <https://sourceforge.net/projects/ring-wincreg>`_ pages.
2. Extract the contents of the bin folder and copy them to the bin folder that is present in the ring language folder ( where the "ring.exe" file is located ).
3. Load the extension and its features in the ring code by using load command as:

.. code-block:: none

	Load "wincreg.ring"
	
.. index::
	pair: Implementation and Usage; How to use

How to use
===========

In order to use "ring_wincreg" extension you have two options to start with:

* Using the functions of the extension directly

* Using the extension through RCRegistry Class Library

I would prefer to use the second option as you can read in (:ref:`RCRegistry-class-library-usage`) section and because I have added some other nice features using Ring that can be used only with RCRegistry class library.

.. index::
	pair: Implementation and Usage; Direct extension's functions usage
	
.. _Use-Extension-Functions-Directly:

Direct extension's functions usage
===================================

You can use the extension functions directly by calling each function as any ring function. In this case you have to load the "ring_wincreg.dll" file directly from the ring code as:

.. code-block:: none

	LoadLib("ring_wincreg.dll")

Then you can call the functions of the extension by their names. 

Lets take a practical example of using this method; in this example we are going to create a key and save a value in it.

.. code-block:: none

	LoadLib("ring_wincreg.dll")
	
	oKey = CRegOpenKey(HKEY_CURRENT_USER, "Software\MyApp")
	
	CRegSetValue(oKey, "version", "4.4")
	
	See "MyApp version is : " + CRegGetValue(oKey, "version")
	
	CRegCloseKey(oKey)
	
This example does the following:

* Create and open a key named "MyApp" in the "Software" key in the main root "HKEY_CURRENT_USER", then assign it's handle (pointer) to the oKey.
* Create new entry named "version".
* Set the value "4.4" to the newly created entry.
* Print the value of the "version" entry after retrieving it.
* Close the key "oKey".

.. index::
	pair: Implementation and Usage; RCRegistry class library usage

.. _RCRegistry-class-library-usage:

RCRegistry class library usage
===============================

RCRegistry class library has been made to simplify using "ring_wincreg" extension by avoid using its long function's names and introduce a nice template for dealing with entries. 

.. code-block:: none

	RCRegistryObject["EntryName"]

Also it reduces the pain of repeatedly mentioning the key handle and typing other parameters with each function call of this extension. 

In a nutshell, this class library brings a special, readable and nice coding experience throughout "ring_wincreg" extension usage.

It has been written in a ring file called "wincreg.ring" which contains also another class named "RCRegEntry" that is needed by RCRegistry class to deal with entries.

To use "ring_wincreg" extension using this library you have to load "wincreg.ring" file to your code, because this file will load "ring_wincreg.dll" extension file and "wincreg.rh" header file that it needs.

.. code-block:: none

	Load "wincreg.ring"
	
Now we have to apply the previous example using this method to clarify the difference.

.. code-block:: none

	Load "wincreg.ring"
	
	oReg = New RCRegistry {
	
		OpenKey([HKEY_CURRENT_USER, "Software\MyApp"])
		
		oReg["version"].SetValue("4.4")
		
		See "MyApp version is : " + oReg["version"].GetValue()
		
		CloseKey()
		
		}

.. note::

	RCRegistry class can represent and deal with one opened key. So in case of dealing with more than one key at the same time we should define a separate RCRegistry Object for each key.
	
As we are really lucky using Ring, we can write the same previous example without creating any object like this:

.. code-block:: none

	Load "wincreg.ring"
	
	New RCRegistry {
	
		OpenKey([HKEY_CURRENT_USER, :Software\MyApp])
		
		Self["version"].SetValue("4.4")
		
		See "MyApp version is : " + Self["version"].GetValue()
		
		CloseKey()
		
		}

In the next sections I'm going to explain how to use "ring_wincreg" extension using RCRegistry class library but I should also list all of the extension functions later on.