# INSTALLATION

1. Download the script
2. Place it in your resources folder
3. Add this to your server.cfg:

```
ensure janiel-progressbar
```

4. Import the SQL file:

```sql
CREATE TABLE IF NOT EXISTS `progress_positions` (
    `identifier` VARCHAR(50) PRIMARY KEY,
    `position_x` FLOAT NOT NULL,
    `position_y` FLOAT NOT NULL,
    `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    `updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

#### 5. Replace Progress Bar Function

Navigate to `qb-core/client/functions.lua` and replace the existing `QBCore.Functions.Progressbar` function with the following code:

```lua
function QBCore.Functions.Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel, icon)
    if GetResourceState('janiel-progressbar') ~= 'started' then 
        error('janiel-progressbar needs to be started in order for QBCore.Functions.Progressbar to work') 
        return false
    end
    exports['janiel-progressbar']:Progress({
        name = name:lower(),
        duration = duration,
        label = label,
        icon = icon,
        useWhileDead = useWhileDead,
        canCancel = canCancel,
        controlDisables = disableControls,
        animation = animation,
        prop = prop,
        propTwo = propTwo,
    }, function(cancelled)
        if not cancelled then
            if onFinish then
                onFinish()
            end
        else
            if onCancel then
                onCancel()
            end
        end
    end)
end 
```

### 💻 Usage

<br>

#### QB-Core Export Example

```lua
-- Simple Progress Bar
exports['janiel-progressbar']:Progress({
    name = "unique_name",
    duration = 5000,
    label = "Doing something...",
    useWhileDead = false,
    canCancel = true,
    controlDisables = {
        disableMovement = false,
        disableCarMovement = false,
        disableMouse = false,
        disableCombat = true,
    },
}, function(cancelled)
    if not cancelled then
        -- Do something when progress is complete
    else
        -- Do something when progress is cancelled
    end
end)

-- Progress Bar with Animation
exports['janiel-progressbar']:Progress({
    name = "unique_name",
    duration = 5000,
    label = "Doing something...",
    useWhileDead = false,
    canCancel = true,
    controlDisables = {
        disableMovement = true,
        disableCarMovement = true,
        disableMouse = false,
        disableCombat = true,
    },
    animation = {
        animDict = "missheistdockssetup1clipboard@base",
        anim = "base",
        flags = 49,
    },
}, function(cancelled)
    if not cancelled then
        -- Success
    else
        -- Cancelled
    end
end)

-- Progress Bar with Props
exports['janiel-progressbar']:Progress({
    name = "unique_name",
    duration = 5000,
    label = "Doing something...",
    useWhileDead = false,
    canCancel = true,
    controlDisables = {
        disableMovement = true,
        disableCarMovement = true,
        disableMouse = false,
        disableCombat = true,
    },
    animation = {
        animDict = "missheistdockssetup1clipboard@base",
        anim = "base",
        flags = 49,
    },
    prop = {
        model = "prop_paper_bag_small",
        bone = 18905,
        coords = { x = 0.10, y = 0.02, z = 0.08 },
        rotation = { x = -80.0, y = 0.0, z = 0.0 },
    },
}, function(cancelled)
    if not cancelled then
        -- Success
    else
        -- Cancelled
    end
end)
```

```lua
RegisterNetEvent('janiel-progressbar:client:progress')
AddEventHandler('janiel-progressbar:client:progress', function(data, cb)
    exports['janiel-progressbar']:Progress(data, cb)
end)
```

#### Check if Progress Bar is Active

```lua
local isActive = exports['janiel-progressbar']:progIsOpen()
```

### Progress Bar Test Scripts for QB-Core&#x20;

#### Instructions:

Once you load this script, you can test the following commands on the client side by typing them in the in-game console:

1. **testprog1**: A simple progress bar without animation or prop, where the user can cancel the process.
2. **testprog2**: An animated progress bar, disabling movement and combat during the animation.
3. **testprog3**: A progress bar with both animation and a prop attached to the player, disabling various controls.
4. **testprog4**: Uses the built-in QB-Core progress bar functionality, with the ability to disable combat actions.

```lua
-- Simple Progress Bar Test Command
RegisterCommand('testprog1', function()
    exports['janiel-progressbar']:Progress({
        name = "test1",
        duration = 5000, -- Duration of the progress bar in milliseconds
        label = "Simple Test...", -- Label text shown on the progress bar
        useWhileDead = false, -- Whether it can be used while the player is dead
        canCancel = true, -- Allow the player to cancel the progress bar
        controlDisables = {
            disableMovement = false, -- Disable player movement
            disableCarMovement = false, -- Disable car movement
            disableMouse = false, -- Disable mouse actions
            disableCombat = true, -- Disable combat actions during progress
        },
    }, function(cancelled)
        if not cancelled then
            QBCore.Functions.Notify('Process Completed!', 'success') -- Success notification
        else
            QBCore.Functions.Notify('Process Cancelled!', 'error') -- Error notification if cancelled
        end
    end)
end)

-- Animated Progress Bar Test Command
RegisterCommand('testprog2', function()
    exports['janiel-progressbar']:Progress({
        name = "test2",
        duration = 8000, -- Duration in milliseconds
        label = "Animated Test...", -- Label text
        useWhileDead = false, -- Can be used while dead
        canCancel = true, -- Can be cancelled by the player
        controlDisables = {
            disableMovement = true, -- Disable movement during progress
            disableCarMovement = true, -- Disable car movement
            disableMouse = false, -- Mouse actions are not disabled
            disableCombat = true, -- Disable combat
        },
        animation = {
            animDict = "missheistdockssetup1clipboard@base", -- Animation dictionary
            anim = "base", -- Animation name
            flags = 49, -- Animation flags (usually controls how the animation behaves)
        },
    }, function(cancelled)
        if not cancelled then
            QBCore.Functions.Notify('Animated Process Completed!', 'success') -- Success message
        else
            QBCore.Functions.Notify('Animated Process Cancelled!', 'error') -- Cancellation message
        end
    end)
end)

-- Prop-Based Progress Bar Test Command
RegisterCommand('testprog3', function()
    exports['janiel-progressbar']:Progress({
        name = "test3",
        duration = 10000, -- Duration in milliseconds
        label = "Prop-Based Test...", -- Label for the progress bar
        useWhileDead = false, -- Can it be used while dead?
        canCancel = true, -- Can the process be cancelled?
        controlDisables = {
            disableMovement = true, -- Disable movement during the progress
            disableCarMovement = true, -- Disable car movement
            disableMouse = false, -- Mouse actions are not disabled
            disableCombat = true, -- Disable combat actions
        },
        animation = {
            animDict = "missheistdockssetup1clipboard@base", -- Animation dictionary
            anim = "base", -- Animation name
            flags = 49, -- Animation flags
        },
        prop = {
            model = "prop_paper_bag_small", -- Model of the prop being used
            bone = 18905, -- Bone ID for attaching the prop (usually related to the player's hand)
            coords = { x = 0.10, y = 0.02, z = 0.08 }, -- Position offset for the prop
            rotation = { x = -80.0, y = 0.0, z = 0.0 }, -- Rotation for the prop
        },
    }, function(cancelled)
        if not cancelled then
            QBCore.Functions.Notify('Prop-Based Process Completed!', 'success') -- Success notification
        else
            QBCore.Functions.Notify('Prop-Based Process Cancelled!', 'error') -- Cancellation notification
        end
    end)
end)

-- QB-Core Built-in Progress Bar Test Command
RegisterCommand('testprog4', function()
    QBCore.Functions.Progressbar("test4", "QB-Core Test...", 5000, false, true, {
        disableMovement = false, -- Do not disable movement
        disableCarMovement = false, -- Do not disable car movement
        disableMouse = false, -- Do not disable mouse
        disableCombat = true, -- Disable combat actions
    }, {}, {}, {}, function() -- Done callback
        QBCore.Functions.Notify('QB-Core Process Completed!', 'success') -- Success notification
    end, function() -- Cancel callback
        QBCore.Functions.Notify('QB-Core Process Cancelled!', 'error') -- Cancellation notification
    end)
end)


```

ESX  FRAMEWORK <br>

Navigate to `es_extended/client/functions.lua` and replace the existing \
`ESX.Progressbar` function with the following code:

```lua
function ESX.Progressbar(message, length, options)
    return exports['janiel-progressbar']:Progressbar(message, length, options)
end

function ESX.CancelProgressbar()
    return exports['janiel-progressbar']:CancelProgressbar()
end
```

\
\
🎮 Usage

```lua
exports['janiel-progressbar']:Progressbar("Message", 5000, {
    useWhileDead = false,
    canCancel = true,
    disableMovement = false,
    disableCarMovement = false,
    disableMouse = false,
    disableCombat = true,
    animation = {
        animDict = "mini@repair",
        anim = "fixing_a_player",
        flags = 49,
    }
})
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://janiel.gitbook.io/janiel-resources/janiel-docs/progressbar/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.